|
As long as the comments are relevant for the reader and help in understanding the structure, yes. I wouldn't go as far as making it required, because that's asking for gems like these;
int i = 0; Printed documentation tends to get lost, even Word-documents and readme.txt files tend to get separated from their archives. However, if you include a 20-page document called "maintenance.cs" and put it completely in /* comment-marks */, it tends to stay with the source.
I are Troll 
|
|
|
|
|
Yes, the example isn't useful.
But, how about a comment on how i is used, since its name isn't descriptive? At least a block comment about what's happening, even a loop with ++i isn't obvious if you don't see what's being counted...
|
|
|
|
|
Although I find myself incline to add comments to the code I always find the code harder to read later, it just makes the code harder to read, it loses style and becomes noise. However, I always add comments when fixing code to have a reference to the ticket and a brief description of the problem.
|
|
|
|
|
I absolutely agree with you.
CDMTJX wrote: said code comments itself
Yes, I know this "excuse" but it is a "bad" excuse  Also others says: Unit-Tests "comment" the code. This is participial correct "good" comments are still required.
|
|
|
|
|
people say "I cannot remember what my code does without help of comment", unless they were programming using a language they were not good at to begin with. Or they suffered some serious head injury or disease, etc. It may take a little longer for me to understand/remember what my code does, there is no single case that I couldn't figure it out eventually.
|
|
|
|
|
"figuring it out eventually" and "not remembering" are two different things! If you have to "figure it out eventually", then you forgot it. Where time is money, it's faster to read a comment than it is to try and figure it out. Plus, there is no way that I can remember the details of code that I did 25 years ago. (that's when alot of current programmers were born!)
|
|
|
|
|
But I did not remember reading a comment has ever helped me. If there are more than one programmers working on the code, then the comments are very likely to be out-dated and cannot be trusted.
Member 3253258 wrote: there is no way that I can remember the details of code that I did 25 years ago
Are you saying you are still maintaining code from 25 years ago? With no exageration? 
|
|
|
|
|
Xiangyang Liu 刘向阳 wrote: But I did not remember reading a comment has ever helped me. If there are more than one programmers working on the code, then the comments are very likely to be out-dated and cannot be trusted.
Have you done much work in assembly language? Coming back to even a somewhat trivial piece of code a week later is much easier if you have code explaining what's going on and why.
It's less necessary with more expressive languages, but now and again it's useful for maintenance. It's also very important when using frameworks and libraries written by others of course!
|
|
|
|
|
destynova wrote: Have you done much work in assembly language?
None. I guess my argument does not apply to people using assembly languages, maybe unix shell script and perl as well. Just wondering, how much comments do you have to write for assembly code? Maybe 10k of comments for every 1k of code?
destynova wrote: if you have code explaining what's going on and why.
You have to write code to explain what you assembly code does? Sorry, can't help it, I know you meant comment instead of code.
|
|
|
|
|
Xiangyang Liu 刘向阳 wrote: None. I guess my argument does not apply to people using assembly languages, maybe unix shell script and perl as well. Just wondering, how much comments do you have to write for assembly code? Maybe 10k of comments for every 1k of code?
Of course assembly language and naturally obfuscated languages like Perl or APL (and very verbose "high level" languages like ATS and ADA) are extreme examples, but I don't think there is a binary division of "languages that need comments" and "languages that need no comments" - more like a sliding scale of understandability (  ) inverse to comment frequency.
Most assembly code I've read seems to have maybe a ratio between 1:1 and 1:5 ratio of comments to code (but the less-commented assembly I read was usually for demos, packers and chipmusic players on the 68000-based Atari ST).
Xiangyang Liu 刘向阳 wrote: You have to write code to explain what you assembly code does? Sorry, can't help it, I know you meant comment instead of code.
Oops, nice catch
|
|
|
|
|
Well, yes, I know what it does, it fires rockets at targets. But for one thing it is several hundred thousand lines of code in several languages, for another some of it is very old and not written by me, and some I ported from some other language so the variable names and so do not correspond to my code guidelines.
I try to make variable names and function names self-documenting, I change them regularly. But I do not have an infinite amount of time and changing e.g. the dll interface makes trouble for everyone else.
I need little comments like
// do not delete this, you will need it if requirement x changes
// don't add null character here because it crashes the interface
// convert here because x delivers degrees not UTM
I have learned if I don't leave these little notes to myself (and to future maintainers) I will come along in a few years and think, oh, I forgot to add the null character here, let's put one in, and then it crashes.
I have met programmers who didn't comment their code on purpose, to keep it mysterious. Usually they were covering up for their own lack of confidence, often caused by their own incompetence and some real dirty and fragile hackwork. These are the kinds of guys who get offended if you ask them if they tested it, of course their code works, am I calling them idiots. But too often they are idiots and there are some very unpleasant surprises in there. As I said, we are firing real missiles here, no room for primadonnas.
------------------<;,><-------------------
|
|
|
|
|
RedSonja wrote: But for one thing it is several hundred thousand lines of code in several languages
Such projects typically have system documentation explaining what each (much smaller) component does. Relying on code comments to understand it can be more dangerous than, say, pressing the big red button.
RedSonja wrote: for another some of it is very old and not written by me, and some I ported from some other language so the variable names and so do not correspond to my code guidelines.
My original post only says people are exagerating when they say "I can't remember what my own code does without comment", it excluded most of the things you mentioned here (code written by others, ported from a different project using a different language, etc.).
RedSonja wrote: I have met programmers who didn't comment their code on purpose, to keep it mysterious. Usually they were covering up for their own lack of confidence
What I found is, the best way to cover up is to provide too much information (no need to make up anything, just include every communication / message / memo related or unrelated to the project) and nobody will be able to accuse you of covering up.
|
|
|
|
|
>Such projects typically have system documentation explaining what each (much smaller) component does.
Hollow laughter
It would be awfully nice if everyone else documented as helpfully as we do, but they don't! As a matter of fact I have to produce a lot of documentation - defence projects, you know - but the real low-down stuff - why I used small int instead of int - does not need to be read by the customer, and QS can get the wrong idea if they see "use small int to avoid access violation". Also we keep official documentation to a minimum, because it's all under version control, and as you rightly say, every memo and every email swamps the useful stuff.
Comments are for me and for future maintainers. Someday you may have to maintain my code and you will be glad of it!
------------------<;,><-------------------
|
|
|
|
|
I always trust documentation within the code more than any other form of documentation. Why?
A) Typically 'system/project documentation' is more related to end-user functional/workflow aspects and does not match technical methodology/coding used to actually accomplish the detailed processes/tasks.
B) Documenting within code verses within a seperate document tends to match the code over the long term much better. It tends to be much more accurate & timely because it is written as the code is written/maintained. As people stick their fingers into an application, you can bet someone (all of them?) will not have (take) the time to update a second 'documentation only' file (ie: Patches/fixes developed & implemented at 3 am tend not to be documented at all except perhaps via archived e-mails, etc).
C) After 40+ years as a developer, I've learned the hard way that I can't depend on any documentation to actually match the code. But the documentation within the code tends to be the closest to the logic used that I'm going to find and it will generally help me get into the mindset of the coder faster (ie: what the heck was this guy thinking when he wrote this peice of s**t ... whoops, I wrote that junk code two years & 4 projects ago and know better (now)).
GoodTime Charlie, VA
|
|
|
|
|
At least for the signal processing code I work on I have to disagree.
The operations are the same more or less, some simple to mid-sized formulas, some scaling, some FFT's, some curve fitting, some filling / sparsing spectra, some vanilla filters. Still, when stringing half a dozen FFT's together to get from A to B the purpose isn't obvious, even if you understand the individual elements.
|
|
|
|
|
If you give appropriate names to functions, structures, variables, etc. you can avoid commenting most of the time.
36. When you surround an army, leave an outlet free.
...
Do not press a desperate foe too hard.
SUN-TZU - Art of War
|
|
|
|
|
"most of the time" is not "all the time"... while I agree that appropiate names are useful, I think that sometimes there's no option but to comment code. Sometimes good names are just not enough...
Cheers!
|
|
|
|
|
Well, behold our mighty brain. Because each person had different mind I think that's why we need to comment our codes 
|
|
|
|
|
I just agree to Fernando A. Gomez F. and savire.
StyleCop will be your friend
|
|
|
|
|
Let your code tell you how, and the comments say what it's supposed to do.
Add as applicable, but not so much as to make reading difficult. Then again, always know your audience. If you're writing a tutorial, comment copiously.
As the programs in the Matrix would know... Those without purpose are deleted.
Same should go to comments.
|
|
|
|
|
I usually think that the name of a method should tell the "what", and the method body the "how", there is just the "why" missing. Although, I've found myself documenting the what an the how when needed, and that has been implementing some numerical methods (http://en.wikipedia.org/wiki/Numerical_analysis[^]) in particular for hashing (I only maintain two of those).
There are other uses for comments, one is keeping tasks and status of the code. I use "ToDo", "Missing" and "InProgress" to tag me tasks. Other is skipping lines of code for test propouses. And I use "Empty" to tell that a code block is empty because it's meant to be empty not because I forgot to write it (Happens often in constructors and virtual methods).
[wrote thinking of Java, C# and VB, this will not apply for most not OO languages]
|
|
|
|
|
Probably some people answer as they wish to do rather they actually do ...
36. When you surround an army, leave an outlet free.
...
Do not press a desperate foe too hard.
SUN-TZU - Art of War
|
|
|
|
|
I cant get enough comments. comments are what keeps me sane when relearning what was done on projects long past. I have found I cant remember what my own code is doing if i'm not working with it constantly, so my code has comments galore.
|
|
|
|
|
Yes. The older I get, the less I remember from one week to the next. And the older the code gets I have to maintain. Without comments I am lost.
Since we produce safety critical code QS uses tools to count how many comments we write. There are standard headers for files and methods so it's easy to get started.
It is also helpful to write the date you changed something, then you can refer back to logbooks and emails for a better idea of what was going on. And if you change someone else's code, put your name in too.
I have written silly comments in the past, for example:
//This is a miserable piece of hackwork and I am ashamed of it
//I don't know why this works. Don't change it
//This is a waste of time but "project management" wanted it
------------------<;,><-------------------
|
|
|
|
|
when it comes to commenting i also comment everything. especially global or scoped variables whose purpose may look obscure. Nothing to do with age, or anything. just something that was drilled into me in college.
commenting your code is king. specially if another programmer looks at the code they can easily tell what function/method/ect .. does what, and if the comments are done right, they should provide a quick overview of the last couple of revisions to that chunk of code.
This information is invaluable to programmers looking at someone else's code for the first time.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
