How should I comment on the if-else structure?

Question

Let's say you have:

if(condition) { i = 1; } else { i = 2; } 

and you need to put comments explaining if and else blocks. What is the most widely read way to do this so that someone can easily pick them up at first glance?

I usually do it like this:

 //check for condition if(condition) { i = 1; } else { //condition isn't met i = 2; } 

which I find not good enough, because the comments are at different levels, so take a quick look at the if comment and the else comment will look as if it belongs to some internal structure.

Put them like this:

 if(condition) { //check for condition i = 1; } else { //condition isn't met i = 2; } 

doesn’t look good to me, as it seems that the whole structure is not commented out (the condition can be large and take several lines).

Something like that:

 //check for condition if(condition) { i = 1; //condition isn't met } else { i = 2; } 

would probably be a better style in terms of comments, but confusing as a code structure.

How do you comment on such blocks?

PS. I am not asking about the reorganization of these two lines of code, only about the style of the code and the formatting of comments.

Answer 1

If you need to comment on if else, I prefer to describe the case where the code reached this point. Especially in code with high cyclic complexity

 if (condition) { // User is taking a course at college x: i = 1; } else { // User is not taking any course at college x: i = 2; } 

Answer 2

Another variant:

 if(condition) { //check for condition i = 1; } else { //condition isn't met i = 2; } 

Answer 3

You should only comment if the code is not self-evident. So do if I explain. How is this possible

 bool fooIsNotReallyGood = ....; if(fooIsNotReallyGood) { ... } else { ... } 

Answer 4

If the code is no longer self-documenting, I would structure it as follows:

 if (someCondition) { // If some condition, then do stuff 1. doStuff1(); } else { // Else do stuff 2. doStuff2(); } 

But then again, that doesn't make much sense if the code is already self-documenting. If you want to add comments due to some complicated state, for example:

 if (x == null || x.startsWith("foo") || x.endsWith("bar") || x.equals("baz")) { doStuff1(); } else { doStuff2(); } 

Then I would decide to reorganize it as:

 boolean someCondition = (x == null || x.startsWith("foo") || x.endsWith("baz") || x.equals("waa"); if (someCondition) { doStuff1(); } else { doStuff2(); } 

Here the variable name someCondition actually sums up the entire condition in a nutshell. For example. usernameIsValid , userIsAllowedToLogin or so.

Answer 5

Go to the conditions of self-comment, then additional comments are not needed. Suppose that the condition is that the maximum loan in value is reached. This gives us:

 if (maximumLoanToValueIsReached) { i=1; } else { i=2; } 

It is not necessary to indicate, when I = 2, that the maximum loan amount has not been reached, since this is self-study. As an aside, I would also rename i into something more meaningful.

Answer 6

I would not comment on these specific cases at all - comments do not add any value to your already understandable code. If you have a very complex condition that is difficult to read, I would consider including it in a function (possibly inline ) with a very clean name.

Answer 7

//condition isn't met seems like a useless comment. But in the case where such a comment is required, I do it like this (C #):

 //check for condition if(condition) { i = 1; } //some other condition else { i = 2; } 

However, if the block is only if-else, I would combine both comments earlier if.

For javascript, I prefer

 //check for condition if(condition) { i = 1; } else { //some other condition i = 2; } 

PS It seems there are as many opinions as there are people :)

Answer 8

This is how I make my comments for if then statement, although I usually think this is not necessary. I like to paste it in line with if / else and paste the tab in the same place

 if ( condition ) //if above the bar { i = 0; k = 1; } else //else if below { i = 1; k = 2; } 

Answer 9

Variables are important, not the conditions themselves.

 if condition: # <condition dependent variable> was <predicated> dosomething() elif othercondition: # <othercondition dependent variable> <predicated> dootherthing() else: # <all variables> <not predicated> doelsething() 

Answer 10

There is no single answer - different people will have different opinions about what is most readable. However, I think there is agreement that comments should really add value to (otherwise self-evident) code and that the style of comments should be consistent.

The way I process comments for conditions that are not immediately clear is as follows:

  // If the condition for a local tree imbalance is met, // juggle the immediate nodes to re-establish the balance. // Otherwise, execute a global balancing pass. if ( somewhat muddled condition ) { ...code... } else // Tree is in local balance { ... more code... } // if/else (tree locally imbalanced) 

The commentary to the final '}' exists primarily to give the end of the condition a more visual weight in order to facilitate reading through the source.

Answer 11

Comments are a very personal matter, and (as seen from some previous answers) generate as much debate as the code.

In simple cases, comments distract from the code. But assuming a more complex condition, I prefer:

 /* ** Comment explaining what the condition ** is trying to determine */ if ( condition ) { /* ** Comment explaining the implications ** of the condition being met */ do_something(); } else { /* ** Comment explaining the implications ** of the condition not being met */ do_something_else(); } 

In any case, comments should not just repeat the code.

Answer 12

You can extract if-else code into methods and name them correctly:

 function main() { checkForCondition(condition); conditionIsNotMet(condition); } function checkForCondition(boolean condition) { if (condition) { i = 1; } } function conditionIsNotMet(boolean condition) { if (!condition) { i = 2; } } 

In such a trivial case, this seems superfluous, but imagine that it has more than one line per if-else branch.