PHP allows commenting code in many ways borrowed from other languages and there isn't established best practices set in the PSR recommendations yet.
There is:
// foo
# foo
/* foo */
/*
* foo
*/
/*
foo
*/
The only established reference is for docblocks which imposes a specific syntax and 2 asterisks at the beginning of the comment to define that this is extractable code documentation for text editors and documentation generators:
/**
* Get the list of parameters for an API call.
*
* @param string $parameters The list of parameters from the URI
* @return array All the main parameters for the query
*/This one is a no-brainer as most IDEs/Editor allow inserting a docblock automatically.
For long comments the formatting I prefer is this one as it is I think clearer for reading the text itself:
/*
We are only interested in target strings with keys in common with our
source strings. Not sending noise to getTranslationMemoryResults() has
a major performance and memory impact.
*/That is to say no mid-asterisks and an indented paragraph to make the text stand out.
For a one line comment, personally I think I almost never use bash-style comments, actually I do but only during development for broken or incomplete stuff to find it easily with grep:
#TODO: do something
#FIXME: do something
#LATER: do something
For one line comments, currently most of our code base uses //:
I think this is OK especially since it seems to be the default in popular text editors I know with PHP when you comment out a line (tested in Atom and Sublime Text ).
But sometimes we mix styles ex:
// Extract, cache and store VCS data
$cache_id = $repo_vcs . $locale . 'healthstatus2';
if (! $stats = Cache::getKey($cache_id)) {
/* generate data */
$commits = $vcs->getCommits();Or we use slashes for a multiline comment:
// Set CSS classes
// If the latest commit is 1 year old or older
So here is my proposal to make it consistent:
- Never use #
- Use // only for a one line comments to explain logic in the code (note the space after the //)
- Use this for general documentation and longer logic explanations:
/*
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut ali
*/
- If your comment explains a logic block or a loop (if, for, foreach, switch…), put it BEFORE the block and not inside, like that:
// build the source locale switcher
$source_locales_list[$repository] = Utils::getHtmlSelectOptions(
$loc_list[$repository],
Project::getLocaleInContext($source_locale, $repository)
);
// build the target locale switcher
$target_locales_list[$repository] = Utils::getHtmlSelectOptions(
$loc_list[$repository],
Project::getLocaleInContext($locale, $repository)
);
// 3locales view: build the target locale switcher for a second locale
$target_locales_list2[$repository] = Utils::getHtmlSelectOptions(
$loc_list[$repository],
Project::getLocaleInContext($locale2, $repository)
);The reason for this last rule is that if you collapse all blocks in your code and your code is well commented you can read the logic of the file by reading the comments, otherwise they are hidden:
// build the source locale switcher
$source_locales_list[$repository] = Utils::getHtmlSelectOptions( ¬
// build the target locale switcher
$target_locales_list[$repository] = Utils::getHtmlSelectOptions( ¬
// 3locales view: build the target locale switcher for a second locale
$target_locales_list2[$repository] = Utils::getHtmlSelectOptions( ¬ @flodolo @TheoChevalier since you are the two other main contributors, would you agree with these conventions? If that is the case, we could turn it into a real issue for the Locasprint, this is kind of tedious work but I think that for a new contributor, it can help learn our whole code base and file structure.
PHP allows commenting code in many ways borrowed from other languages and there isn't established best practices set in the PSR recommendations yet.
There is:
The only established reference is for docblocks which imposes a specific syntax and 2 asterisks at the beginning of the comment to define that this is extractable code documentation for text editors and documentation generators:
This one is a no-brainer as most IDEs/Editor allow inserting a docblock automatically.
For long comments the formatting I prefer is this one as it is I think clearer for reading the text itself:
That is to say no mid-asterisks and an indented paragraph to make the text stand out.
For a one line comment, personally I think I almost never use bash-style comments, actually I do but only during development for broken or incomplete stuff to find it easily with grep:
For one line comments, currently most of our code base uses //:
I think this is OK especially since it seems to be the default in popular text editors I know with PHP when you comment out a line (tested in Atom and Sublime Text ).
But sometimes we mix styles ex:
Or we use slashes for a multiline comment:
So here is my proposal to make it consistent:
The reason for this last rule is that if you collapse all blocks in your code and your code is well commented you can read the logic of the file by reading the comments, otherwise they are hidden:
@flodolo @TheoChevalier since you are the two other main contributors, would you agree with these conventions? If that is the case, we could turn it into a real issue for the Locasprint, this is kind of tedious work but I think that for a new contributor, it can help learn our whole code base and file structure.