How to comment on the most read statements

Question

I am trying to make my code understandable to future readers.

I've always had problems with how to write comments in if if comments to make it the most understandable.

It may seem trivial, but this is what has always bothered me

Here is an example:

if ( !$request ) { $request = $_SERVER['REQUEST_URI']; } 

Somehow I can think of commenting on it

 // If request doesn't exist if ( !$request ) { // Set request to current request_uri $request = $_SERVER['REQUEST_URI']; } // Check for a request if ( !$request ) { $request = $_SERVER['REQUEST_URI']; } // Request doesn't exist if ( !$request ) { // Set request $request = $_SERVER['REQUEST_URI']; } 

Not the best example, but the way I see him is the endless ways of saying it.

I have never worked on a team, so I do not have much experience in other people reading my code.

What are your impressions of the best way to use the word to make it available to future coders.

Answer 1

In the cases you provide, I would not comment on them at all. I use only comments in the body of the method / function when doing something extremely complex or non-obvious - two things that I try to avoid. Just put one short comment at the beginning of the method.

Answer 2

In this specific example, I would not comment on the if statement - you are repeating what is said in the code.

I could see a case where the test code is complex:

 if (a == 3 && b && c > 2) 

but in this case, I will first try to extract a method with a meaningful name:

 if (markerIsValid(a, b, c)) 

Only if this was not possible, I will comment on the test.

Answer 3

My recommendation is not to state the obvious.

Reading if (! $ Request) says - if the request does not exist. I do not need a comment for this.

If you have several checks (this || (that && this-too)), I would go for the creation of a method that returns a boolean with the result. Then your method name is your comment, which is usually better than the actual comment.

Answer 4

I do not want to say that it does not matter, but basically it depends on the preferences of the programmer. Better yet, write the predicates in the if statement to read without comment.

This is easier in some languages ​​than in others. For example, some languages ​​use semantic negation words such as not , which can make predicates easier to read. Moreover, if the reader in question is a fairly programmer, he should be able to process the general test logic without the need for manual annotation.

Bottom line: use your discretion.

Answer 5

Using your example, I usually prefer the following style:

 if ( !$request ) { // The request is not yet set, so retrieve it. $request = $_SERVER['REQUEST_URI']; } 

I like to place it inside an if block so that it looks better when there is an else or else if .

 if ( !$request ) { // The request is not yet set, so retrieve it. $request = $_SERVER['REQUEST_URI']; } else { // Comment about doing something else here. } 

Answer 6

Read the Robert Clean Code book.

http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

Comments should only be used to explain concepts that the code cannot explain itself.

Answer 7

When I write code comments, I try either

• Explain a complex, non-obvious procedure (reg ex is a great example) or
• Explain why I do what I do.

Stop by Code Complete . McConnell has a wonderful chapter for comment.

I would recommend the book to anyone writing code.

Answer 8

Remember: rarely do you need inline comments to say what the code does; if you do not explain a particularly crude algorithm, the code should take on this load without comment. (And if this is not possible, you may need to make the variable names more descriptive.)

However, comments explaining why the code does what it does can be extremely valuable. (Assuming it's not damn obvious, if so, just skip the comment.)

After that, it is really a matter of personal taste, although I defend the sequence. Personally, when I comment on if trees, I prefer to backtrack on comments so that they are in line with a sentence that they explain:

 if ( !$request ) { // If the request isn't set, foo() will barf; the current // request is a suitable default. $request = $_SERVER['REQUEST_URI']; } 

Just make sure your comments justify their existence, and the rest is gravy.

Answer 9

I do not like reading code filled with comments. The code should be clear. I usually comment on large, difficult to understand parts of the code, not separate and trivial lines.

Answer 10

This is very up to the programmer. I will provide two tips:

Do not state obvious

Take the following example:

 // If request doesn't exist if ( !$request ) { 

In the above case, the comment simply duplicates the code (I understand that it was an example, but I still want to do this). Focus on clarifying what might not be obvious in the code. On the other hand...

Do not assume that all developers know that you know

Look at your code and imagine that you are a relative newbie. Would you understand that? If not, check with comments.

Answer 11

I am using this form:

 // Full Comment if (condition) { action; action; } 

Because when code flushing is turned on, you get something similar to this:

 // Full Comment if (condition) { ...} [+] 

Instead of this:

 // Half Comment if (condition) { ...} [+] <---button to click to get the rest of the comment 

Answer 12

You do not need. Just refactoring by introducing explanatory variables :

  if ( (platform.toUpperCase().indexOf("MAC") > -1) && (browser.toUpperCase().indexOf("IE") > -1) && wasInitialized() && resize > 0 ) { // do something } 

becomes:

 boolean isMacOs = platform.toUpperCase().indexOf("MAC") > -1; boolean isIEBrowser = browser.toUpperCase().indexOf("IE") > -1; boolean wasResized = resize > 0; if (isMacOs && isIEBrowser && wasInitialized() && wasResized) { // do something } 

Answer 13

The second link to Code Complete: a great book that should be read for programmers.

There are some things that I would like to keep in mind:

• Do not repeat the code : explain what it does in general terms.

• Never assume that something is obvious ; Refine and explain the code.

• Use functions to clarify your meaning if necessary: ​​make the name related to what is being done.

• Never assume that the code is self-explanatory - even if it is. Most importantly, never assume that a particular “idiom” code will be read by anyone who understands it: explain what the code does.

As someone said, don't get negative if you can: I had a programming class where a negative IF was not allowed under any circumstances. If you are really stuck, you can use your native language (e.g. English) to your advantage. Instead:

 if (!eof(f)) 

You can say:

 if (moreData(f)) 

In your example, I would go with something like this (if I understood correctly):

 // Make sure that we have a valid request: // set it if it is not set already if ( !$request ) { $request = $_SERVER['REQUEST_URI']; } 

I would add: do not put comments in the field . A box is difficult to maintain and maintain: one spends more time fixing a box instead of keeping comments current.

Answer 14

Examples if the statements are simple enough to not require comment. Over commenting can be dangerous, because then you need to support not only the code, but also the comments. For complex if statements, you have the right idea - stick with the comment right above the if statement.

Answer 15

I agree with neil, for this example it’s pretty obvious in any case that you are checking to see if the request exists. Entering many comments can make your code less readable. (i.e. commenting out each line or any other line of code)

Answer 16

I agree with Evan - write your code for reading. Assuming you have complex code that needs to be commented out, I use and prefer the first option, which looks like readable text.

Answer 17

Comments should explain code that is not clear. In most cases, code that is not clear must be rewritten to be clear. In your example, I do not see any comments at all. In this way, you can answer how to formulate your comments in order to focus on making the code more readable so you don't need comments.

When they are needed, they should not just be pseudo-code, but should provide information that the reader does not have right away. An example would be a comment in a “new” statement indicating where the memory is released.

Answer 18

I would focus more on making the code itself self-documenting, which means good variable names, function names, etc. Comments are better discarded for functions or blocks of code than single lines.

Answer 19

Do not comment on the obvious if your audience is not, for example, newcomers ( 1 ).

Answer 20

If your variables are well-named, your if statement should be fairly self-contained.

In addition, using some “strategic” comments, everything should be in plain English.

Check out the definition of “tactical” and “strategic” comments in this document http://www.doc.ic.ac.uk/lab/cplus/c++.rules/chap4.html#sect3

Answer 21

See this similar / identical question: Where to put comments in an IF THEN ELSE construct

Answer 22

Name your variables / methods so that the comment is trivial.

If you have many complex conventions in your case, then extract this condition into a logical function / method that clearly explains what it does.

If you need to comment on your conventions, you are probably on your way to Arrow Anti-pattern .

Use the compiled refactoring method to help with this. Make sure your methods / functions are encapsulated at the same level of abstraction. Polymorphism allows you to completely get rid of conventions. This is better because behavior is determined dynamically at runtime. This is another thing you should encode (and support).

Answer 23

As already mentioned, maybe your example is too simple to really have an appropriate comment on it, but here are some general tips:

• it is usually easier to read “positive” conditions than negatives (not a condition)

• feel free to retrieve methods that will have a detailed name that will communicate intentions and avoid the need for some comments. In your case, let's say you create:

   function getRequest( $req ) { if( isset( $req ) ) { return $req; } else { return $_SERVER['REQUEST_URI']; } } 

  but again, we need a more suitable example, in your case this may be redundant

• should read:

  • Refactoring Martin Fowler

  • Writing solid code

  • Code completed

Answer 24

I understand that this is not applicable in your specific example, but, as a pedant, I have to say: if possible, they do not lead to a negative case. It is harder to read no matter what the comment. In general, I would agree that the test should be clear without comment, or you may need to extract it using the semantic method.