Stop commenting your code just to say you did
1–10 of 76 posts
Re: Stop commenting your code just to say you did
#2This is one of the reasons that programmers who haven't read much of other people's code are a liability. They're as lost as novelists who don't read books.
The difference comes down to empathy: if you can get inside the head of your future readers, you'll know when to comment, and what to name that function, and how long the functions should be, etc...
Re: Stop commenting your code just to say you did
#3I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e.
// do blah blah
obvious_thing;
obvious_thing;
obvious_thing;
obvious_thing;
// do something else
obvious_thing;
obvious_thing;
obvious_thing;
obvious_thing;
This is really useful in something like drawing code.
Re: Stop commenting your code just to say you did
#4Yes
If you write this: x = 1; // sets x to 1 I HATE YOU
Explain the WHY not the WHAT
It's the same crap with the Hungarian notation, where half MS didn't get how to do it properly. It's not the computing type, it's what the variable represents. Thank you, I know this is an int, the compiler knows it's an int. What I need to know is what this is counting/representing/etc
Re: Stop commenting your code just to say you did
#5I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e. // do blah blah obvious_thing; obvious_thing; obvious_thing; obvious_thing; // do something else obvious_thing; obvious_thing; obvious_thing; obvious_thing; Even though none of the lines really need documentation, having the comment ensures that you can quickly jump in when you come back later. This is really useful in so…
Here's a better solution:
function main()
do_blah_blah();
do_something_else();
end
function do_blah_blah()
obvious_thing;
obvious_thing;
obvious_thing;
obvious_thing;
end
Re: Stop commenting your code just to say you did
#6Thing is, just like with code, you write good comments by throwing away bad ones. The writing of the bad ones is not optional.
Re: Stop commenting your code just to say you did
#7God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code...
Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code...
Or someone needs a bit of natural language to provide an anchor in their code.
The important thing here, I think we can all agree, is that we are smarter than that person.
Re: Stop commenting your code just to say you did
#8I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e. // do blah blah obvious_thing; obvious_thing; obvious_thing; obvious_thing; // do something else obvious_thing; obvious_thing; obvious_thing; obvious_thing; Even though none of the lines really need documentation, having the comment ensures that you can quickly jump in when you come back later. This is really useful in so…
Here's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..
It should be pointed out that with inlining, both versions are exactly the same at runtime.
Descriptive function names never lie, comments often do.
Re: Stop commenting your code just to say you did
#9I suspect part of this is enforced by TA markers in university.
When marking a TA isn't trying to understand the code, they just do not have time for that. So when evaluating the documentation or comments portion of the mark they just scroll through and see how much gray is on their screen. No marks are ever deducted for bad comments.
The situation can get so silly I've had TAs complement my code and the design then deduct full documentation marks.
This has led some people I know to go over their code before submission and add worthless comments. To them "documentation" is a separate step which occurs after you've written and tested everything. The whole situation is a shame.
Re: Stop commenting your code just to say you did
#10Earlier quoted context omitted.
Here's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..
It should be pointed out that with inlining, both versions are exactly the same at runtime. Descriptive function names never lie, comments often do.
> Descriptive function names never lie
Beg pardon[0]?
function _utf8Encode(&$arr){
for($i=0;$i public static string ReturnEmptyStringIfNullElseValue(string value) {
if (value == null) {
return "";
} else {
return value.ToString().Trim();
}
}
[1] http://thedailywtf.com/Articles/Common-Functions,-not-Common...