Do you really mean the "thought process of the implementation"? The design should be properly conveyed in the design artifacts.
Comments are useful in conveying the thought process of the design.
Do you really mean the "thought process of the implementation"? The design should be properly conveyed in the design artifacts.
personally, i disagree about block comments above functions, describing the input and output. the names of the function and variables should be descriptive enough that you don't need this big ass comment block above.
if you have the following function:
Address getPersonsAddress(int personId, String firstName, String lastName)
it would be 100% useless and a waste of time adding in a block comment describing that the function gets a persons address, describing what it takes a perons ID, their first name, and their last name as parameters, and returns their address. waste of time and real estate.
In addition to what Train said, this is a confusing interface; why should I enter both an ID and a name? What happens if I enter a valid ID and a valid name of two different people? If the interface is like this for a reason and cannot be refactored to something self-explanatory, it needs comments.Address getPersonsAddress(int personId, String firstName, String lastName)
it would be 100% useless and a waste of time adding in a block comment
In addition to what Train said, this is a confusing interface; why should I enter both an ID and a name? What happens if I enter a valid ID and a valid name of two different people? If the interface is like this for a reason and cannot be refactored to something self-explanatory, it needs comments.
very rarely should a block comment be used before a function. if you are doing a full block comment for getters and setters, you are doing it wrong.
And I disagree with this statement. Getters and setters and very simple functions are about the only thing that I would support having no block comments on.
Block comments are easy to ignore, don't clutter the code, and can be very useful for complex function usage (especially if some autodocumentation tool is being used).
on another note, i'm actually working with some 3rd party software at work that i'm integrating into our application. they have some API calls such as getField(String st, int i1, int i2, int i3) and they have absolutely no javadoc documentation or comments in their API and it has been a total fucking pain in the ass trying to work with it lol.
but me personally, i think the problem could be solved by simply having better variable names instead of adding a big comment. but still if you are creating an API for other people to use, then the javadoc comments should DEFINITELY be before functions that aren't getters and setters.
Maybe it's about job security. If no one knows what the heck is some module doing but you, they'll think twice before sacking you, right?A lot of programmers must think their sh*t doesn't stink.
"Why, my code is so super-awesome it's obvious to anyone but a nimrod what I'm doing."
<script type="text/javascript">
function isLeap(year){
if(year%4){return false;}
if(year%100){return true;}
if(year%400){return false;}
return true;
}
</script>Maybe it's about job security. If no one knows what the heck is some module doing but you, they'll think twice before sacking you, right?
Sure, the code can be more readable by re-writing each condition like "if(year%4!=0){...}", but that would impact performance with additional and unnecessary comparisons to 0. If I used this code in the future as part of some loop for checking millions of records, there could be a significant performance impact.
Sure, the code can be more readable by re-writing each condition like "if(year%4!=0){...}", but that would impact performance with additional and unnecessary comparisons to 0. If I used this code in the future as part of some loop for checking millions of records, there could be a significant performance impact.
While some languages allow you to perform a Boolean check on an integer, I'd argue that it fails a readability test. Although, do note that I said some languages. For example, Java does not allow integer operations to be checked like that.
Maybe this is an example of when simple code still needs comments?
Leap year rules:
- Every year divisible by 4 is a leap year.
- But every year divisible by 100 is NOT a leap year
- Unless the year is also divisible by 400, then it is still a leap year.
It took me a while to get the logic right because I keep reading the comparisons incorrectly. From what I can tell, this is perfect:
HTML:<script type="text/javascript"> function isLeap(year){ if(year%4){return false;} if(year%100){return true;} if(year%400){return false;} return true; } </script>
...but it's still confusing to read, for me. Maybe it's because I don't code professionally, but I just keep reading the first condition as "if year is divisible by 4 ..." It should actually read: "if year is NOT divisible by 4 ..."
Sure, the code can be more readable by re-writing each condition like "if(year%4!=0){...}", but that would impact performance with additional and unnecessary comparisons to 0. If I used this code in the future as part of some loop for checking millions of records, there could be a significant performance impact.
I gotta agree with Ichinisan on this one - I think a short comment would help here, either that or explicitly comparing to 0. At first look I made the same mistake of reading "year%4" as 'year divisible by 4', only when I continued reading his post I realized the code is correct afterall. If one is superficially looking at this, I think it's too easy a mistake to make.That code is completely comprehensible to me just based on the function name.Maybe this is an example of when simple code still needs comments?
Leap year rules:
- Every year divisible by 4 is a leap year.
- But every year divisible by 100 is NOT a leap year
- Unless the year is also divisible by 400, then it is still a leap year.
It took me a while to get the logic right because I keep reading the comparisons incorrectly. From what I can tell, this is perfect:
HTML:<script type="text/javascript"> function isLeap(year){ if(year%4){return false;} if(year%100){return true;} if(year%400){return false;} return true; } </script>
...but it's still confusing to read, for me. Maybe it's because I don't code professionally, but I just keep reading the first condition as "if year is divisible by 4 ..." It should actually read: "if year is NOT divisible by 4 ..."
Sure, the code can be more readable by re-writing each condition like "if(year%4!=0){...}", but that would impact performance with additional and unnecessary comparisons to 0. If I used this code in the future as part of some loop for checking millions of records, there could be a significant performance impact.
I gotta agree with Ichinisan on this one - I think a short comment would help here, either that or explicitly comparing to 0. At first look I made the same mistake of reading "year%4" as 'year divisible by 4', only when I continued reading his post I realized the code is correct afterall. If one is superficially looking at this, I think it's too easy a mistake to make.
I think what Markbjn means by "totally comprehensible based on the function name" is that as a CONSUMER of the function, you don't need to know what it going on inside the method. Treat it as a "black box". In a function such as this, which has a single strongly typed parameter and a boolean response, with zero outside dependencies, the internals should never have to be worried about again, once the function is written and tested the first time.