I’ve always said “WHY” is the most important thing to comment, and always gotten static over it. I usually include a file, or big comment block somewhere where it makes sense, that just states the purpose and general design philosophy of an application, and any important assumptions in force.
All that aside, I’ve actually noticed a trend in a lot of developers to actively NOT READ COMMENTS. Whether because they are used to comments being bad, inaccurate, out of date, nonexistent, or maybe they just don’t like to read seems to vary, but on many occasions Ive been asked to assist someone figure out some old code or another, and figured out their problem just by reading the comments and groking the intent of the code rather than trying to read every last line of it.
Another related trend I’ve noticed is a tendency to rely too much on debugging to figure out what code does rather than interpreting it mentally while reading thru it. I’ve watched too many developers go line by line in a debugger when simply looking at the code, a call chain, some names, and a comment or two is usually sufficient to pinpoint an area that is likely to have problems.
And finally, my big pet peeve is when developers make code changes to legacy / older code and make no comment that they are making a change or WHEN or WHY they are making a change. Source Control is great and all that, but I’d rather not have to review all possible versions of a file directly to ascertain when a change was introduced and for what reason if I have to reconstruct how something bad was permitted to happen in PROD, how long it was possible for it to occur, and what else was affected.
Often the most useful comments are the ones that have little to do with the code itself and more to do with flagging bug fixes and functionality changes with a date and a justification (even if its just a reference to a bug tracker system or ticket).
The problem with your ternary operator example [ i.e. (condition) do_true : do_false ] is the same as the problem with one-line-if’s.
If you recall, in C-ish languages you can have something like:
if (condition) do_true elsedo_false
So, How do you interpret:
if (condition1) if (condition2) do_true else do_false
is it:
if (condition1)
``if (condition2)
else
``do_true3
OR:
if (condition1) {
``if (condition2)
````do_true2
``else
````do_true3
}
Before you think it's obvious, realize that in BOTH examples the ``if'' operator has more than one subsequent line after it. Neither are, intuitively at least, ``one-line'' if's. Convention says to use the second construct, which is even framed by the rule: ``else'' matches the closest ``if.'' Note that, if not for this rule, the original sentence would be a member of a language generated by an ambiguous context-free grammar. The decision is entirely semantic. If you feel it's obvious then it's only because you've been in the game for a long time. When you write code, it is potentially around for generations. (There is still COBOL floating around out there-- it is STILL alive). Don't take language shortcuts for granted. Use the ternary operator in truly unambiguous situations only. In fact avoid using it, if you can. Use WORDS not SYMBOLs. There are already enough symbols. Turn on your coding verbosity!
This is something i don’t understand at all - commenting code is damnably good practice - why do so many developers see it as a sign of weakness? Do you know your language inside out like keanu reeves knew kung fu in the matrix? Do you not own any reference books? No bookmarks to developer sites? Comments can be seen as a local reference; explaining the why of a piece of code in a local context.
I was actually told today, after inquiring as to why there were no comments in a class - ‘well, if you’re too stupid to understand it i can add some comments’. No one want’s to parse a code file in their head - comments let you blitz through some code, seeing what it does at a glance.
And if you do feel the need to decry commenting, a word of warning: there is no way you can without coming across, at best, as arrogant, and at worst as the worst type of socialogically maladjusted retard.
Hi all. Everything has its wonders, even darkness and silence, and I learn whatever state I am in, therin to be content
I am from Oman and know bad English, please tell me right I wrote the following sentence: Subscribe to our newsletter and receive our exclusive special report on airline ticket.
Code should be documented using uml, data dictionaries, other diagrams etc.It is not productive to search through code, it is better to design ,prove your algorithm-solution in paper and then proceed to implementation. Not to mention that there must be always specs explaining the purpose of every element.
“Well…I hate to have to point this out, but the double use of ?: in that example just highlights a bad coding technique. How much clearer would it have been NOT to use the horror that is ?: ?”
You’re kidding, right? You prefer a bunch of if/then/else statements for such a simple assignment? It’s far more readable with the ? : pattern - unless you work with a language that doesn’t have that pattern - but obviously you don’t expect your code to be read by someone who isn’t familiar with the language syntax. If/then/else introduces flow control which is always more mentally taxing than a simple binary conditional.
I think the post and the examples were bang-on, personally. I admit I’ve strayed from this rule once in a while, most often when writing Web Methods (which can’t be overloaded), and the names themselves would be excessively long if they described the differences. Then again, those aren’t technically comments, they’re description attributes.
In my work, the times that I feel comments most lacking is when I don’t know how functions are intended to be used, or what the point of them is.
I can read code, and figure out what it does, but I don’t know why that library function was added, and without grepping the whole source tree to see how it’s used, I don’t know why it’s there.
Sometimes, I couldn’t care less about how a method actually works, but I just want to know what, as a whole, it does. What is it’s one-sentance description? What does it expect as inputs? Outputs? Error codes? Exceptions? And if it’s very involved, how about an example? The XML commenting system of .NET is absolutely fantastic, and I find that to be the most important part of a particularly large project with lots of developers – just document the description, inputs, and outputs of all public methods and it helps everyone get along much nicer.
And if your code is written and refactored into small enough chunks, then one should (in theory) not have any methods that are too painful to sit down and grok should their contents be under-commented but you understand the overall gist of the method.
So I guess I’m suggesting the idea that method header comments are more important than actual implementation-specific comments.
Look at it another way.
If the purpose of a sub is documented with the ins and outs, yet the implementation is undocumented spaghetti code assembler and it’s causing a bug, the person fixing the code doesn’t need to understand how the old code works – he can try and learn from it – sure, but it would probably be easier and cleaner if he just re-wrote it from scratch and didn’t try to copy/paste from the old implementation except when it’s convenient.
Couldn’t disagree more. As a one-time maintenance programmer, I couldn’t care less why code works, I only care why it DOESN’T.
By some strange co-incidence, the lines of code I had to fix never, ever had comments. Code with well-written comments rarely came to my attention, except to suggest where else I should look.
“Comments are more Important than Code”. This is a verty good Article by Jef Raskin. Writing good comment is difficult. To teach yourself to write comments before you write the code is a discipline. I think the quality goes up if you do this well. The rest for writing no comments is an excuse for not willing to do it. I did not start as a software developer with writing comment. After I read more then 100.000 codelines from others I realized the importance of GOOD comments. You not only write comments for yourself but also for the developers who have to maintain your software.
Class, variable, function etc. names should be all the documentation you need for a class. The rest of documentation should be in tests written as a specification of the class.
Comments to me basically say I am unable to give this function a name that appropriately describes what it does, so i will document the intricacies for my future self just in case i forget.
Sheehan.