>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #2355209. --> Reported by: [ianthomas_uk](https://www.drupal.org/user/1877338) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Both core and contrib have code that is intended for internal use only, and should not be called from other contrib modules or custom code. This can be functions, interfaces, or certain methods.</p> <p>On D7, this was indicated for functions by prefixing the function name with an underscore. That's great if you know what it means, but isn't at all clear if you don't know the convention.</p> <p>We should have an indication in the docblocks for these functions or interfaces. Currently we have either:</p> <ul> <li>@internal</li> <li>Nothing (most functions)</li> <li>"(internal use only)" in the one line description (e.g. <code>_theme</code>)</li> <li>@deprecated (e.g. <code>_drupal_add_js</code>) </li></ul> <p>Of these three I think "(internal use only)" is the best because it's most visible, but it's still not totally clear what qualifies as internal and uses characters in the one-line description. @deprecated is just plain wrong - the functions can still be used, but only by internal code.</p> <h3 id="summary-benefits">Benefits</h3> <p>If we adopted this change, the Drupal Project would benefit by ...</p> <h3 id="summary-supporters">Three supporters required</h3> <ol> <li>Gogowitsch </li> <li>joachim</li> <li>{link to user}</li> </ol> <h3 id="summary-proposed-changes">Proposed changes</h3> <p>Provide all proposed changes to the Drupal <a href="https://www.drupal.org/docs/develop/standards">Coding standards</a>. Give a link to each section that will be changed, and show the current text and proposed text as in the following layout:</p> <h4>1. <a href="https://www.drupal.org/docs/develop/standards/coding-standards#s-functions-and-variables">documentation on function declarations</a> </h4> <h5>Current text</h5> <blockquote><pre class="codeblock"> <div class="codeblock"><code class="language-php">function funstuff_system($field) {<br>&nbsp; $system["description"] = t("This module inserts funny text into posts randomly.");<br>&nbsp; return $system[$field];<br>}<p>Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate.</p> <p>Anonymous functions should have a space between "function" and its parameters, as in the following example:</p> <pre> <div class="codeblock"><code class="language-php">array_map(function ($item) use ($id) {<br>&nbsp; return $item[$id];<br>}, $items); <h5>Proposed text</h5> <blockquote><pre class="codeblock"> <div class="codeblock"><code class="language-php">function funstuff_system($field) {<br>&nbsp; $system["description"] = t("This module inserts funny text into posts randomly.");<br>&nbsp; return $system[$field];<br>}<p>Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate.</p> <p>Anonymous functions should have a space between "function" and its parameters, as in the following example:</p> <pre> <div class="codeblock"><code class="language-php">array_map(function ($item) use ($id) {<br>&nbsp; return $item[$id];<br>}, $items);<p>A function outside of classes, interfaces and traits cannot be marked as private. Instead, you can mark functions that are not to be called from outside the project by starting their name with an underscore. In addition, use the @internal annotation.<br> </p><pre class="codeblock"> <div class="codeblock"><code class="language-php">/**<br> * @internal<br> */<br>function _private_funstuff_system($field) {<br>&nbsp; $system["description"] = t("This module inserts funny text into posts randomly.");<br>&nbsp; return $system[$field];<br>} <h4>2. Repeat the above for each page or sub-page that needs to be changed.</h4> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ol> <li><del>Create this issue in the Coding Standards queue, using the defined template</del></li> <li>List three supporters</li> <li>Create a Change Record</li> <li>Review by the Coding Standards Committee</li> <li>Coding Standards Committee takes action as required</li> <li>Tagged with 'Needs documentation edits' if Core is not affected</li> <li>Discussed by the Core Committer Committee, if it impacts Drupal Core</li> <li>Documentation updates <ol> <li>Edit all pages</li> <li>Publish change record</li> <li>Remove 'Needs documentation edits' tag</li> </ol> </li> <li>If applicable, create follow-up issues for PHPCS rules/sniffs changes</li> </ol> <p>For a fuller explanation of these steps see the <a href="https://www.drupal.org/project/coding_standards" title="Coding Standards project page">Coding Standards project page</a></p> </code></div></pre></code></div></pre></code></div></pre></blockquote></code></div></pre></code></div></pre></blockquote>