|
Amen, brother. Comments should describe 'why' or 'how' you are doing something. Most programmers know the 'why' and the 'how' intrinsically, but can't or won't express it verbally in their comments.
Software Zen: delete this;
|
|
|
|
|
Gary Wheeler wrote:
Comments should describe 'why' or 'how' you are doing something.
This is a really good point. Describing "what" you're doing is often nothing more than psuedo-coding the code itself. But describing why something is done in a particular way, or how it is being done, is much harder because it often involves the surrounding context. Where does one start in describing why? I have this problem myself when trying to explain the why of the AAL. It's darn hard, but worth the effort. On many occasions, after explaining the "why" to myself, I end up saying to myself, "gee, that's a stupid reason!". 
Marc
Latest AAL Article
My blog
Join my forum!
|
|
|
|
|
In my case, the 'why' and 'how' are usually pretty easy. The software I work on does process control (we build high speed ink jet printers[^]), so the why's and how's are usually related to something the hardware is doing. A dilettante would say that, if you're having trouble stating 'why', maybe you need to think about the approach (the 'how') a little more. My how's usually are limited to difficult algorithms.
As an example, I needed a wildcard matching routine. I found one on the C/C++ User's Journal web site. Unfortunately, the routine wasn't usable in its original state. It wasn't well structured (multiple exits), didn't use our naming conventions, and didn't provide a couple of minor behaviors I wanted. I ended up rewriting the routine. For documentation of my version, however, I included the code for the original in a block comment, including the web address of the original article.
Software Zen: delete this;
|
|
|
|
|
Gary Wheeler wrote:
so the why's and how's are usually related to something the hardware is doing.
That's cool. I love working with hardware. In some ways, it makes programming easier because the hardware creates a bounded space in which the software must function. Sort of like communicating with a child--you have to use small words and simple sentences. (OK, that's a really off-the-cuff analogy).
Gary Wheeler wrote:
however, I included the code for the original in a block comment, including the web address of the original article.
Nice. I've been doing that with the AAL articles (as far as weblinks, authors, etc) for code that I use that I've found on CP. Personally, one of the things I find even more appealing than writing the articles is the connections that form from people posting links to things that they've encountered. Very enriching.
Marc
Latest AAL Article
My blog
Join my forum!
|
|
|
|
|
Marc Clifton wrote:
Sort of like communicating with a child
You ought to see one of our CMYK machines acting like a non-potty-trained toddler. Why is it the yellow head always lets go first? 
Software Zen: delete this;
|
|
|
|
|
Good point.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch ![Green Alien | [Alien]](https://www.codeproject.com/script/Forums/Images/alien.gif) "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Programmers than can express themselves in english are worth 10-15k more a year.
|
|
|
|
|
...for tranfering the responsibility from the writer to the reader.
"What? You don't understand my code?- Learn reading, it's all commented"
But a comment make any code running...
void main(void)
{
// char *pszText = new char[2];
// pszText[3] = '?';
}
...yeah, it works 
|
|
|
|
|
That is one use for commenting.
void main(void)<br />
{<br />
<br />
}
I think my mod is good
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
I've tested it, it works. Cool stuff. Comments are really powerful  !
|
|
|
|
|
Comments are a waste of time.
Future developers will either understnad it or not.
If they can't understand it without comments, then that's actually good, because you don't wan't some 3rd rate hack messing with your masterpiece.
Understandable code, is subjective.
Understandable to who, and for what purpose.
What really matters is it can build without problems, then it can run without BSODs.
Too much emphasis is place on this stupid unstandability notions.
What really nmatters is if the creator can keep the whole train of thought as he/she types away.
Having to add comments etc, is only going to ruin productivity.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
You are obviously trolling but this is still worth mention; Any fool can get compiled code, it is at run-time that counts.
Paul Watson
Bluegrass
Cape Town, South Africa
Crikey! ain't life grand?
|
|
|
|
|
Paul Watson wrote:
You are obviously trolling but this is still worth mention;
Not entirely Paul. I realise that a lot of people will disagree with me, and what I ahve just said goes against the popular opinion, but I do believe it.
Paul Watson wrote:
Any fool can get compiled code, it is at run-time that counts.
Agreed, clients are happy if you can produce quality goods at a reasonable price. Software is no different apart from a few exceptions.
If a solution is required, it doesn't matter if it is created in C++. C# VB, Pascal, Forth, Lisp, or Lego. What matters is if it meets the requirements of the client. Commenting and creating understandable code is a micro issue.
For instance C++ allows a developer to break his work into classes, what really matters is if the conventions for calling procedures in the classes are strong. If the class has been made bug-free and robust it never needs a second look. So what's the point in internal understandability or comments ?
If a class has problems, the developer should just rewrite it better the next time.
The whole issue of reusability is crud if you are going to have to be perpetually maintaining code, as the flow on effects are going to be horrendous. It appears these days 90+ % of developers spend there time not actually developing but maintaining. This proves that the code initially accepted was not up to scratch.
Adding comments and attempting to make code understandable to third parties, just proves that you have no confidence in the future of your code.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
So what's the point in internal understandability or comments ?
When the initial developer of an application is fired/leaves and the client has to get a new developer to maintain the application.
We recently had this exact problem. A client was in trouble as a contractor had developed a system for them and then buggered off to London. They needed some new features and so sent us the code. It was very hard to read code. Technically it worked well, the architecture was sound and the system at run-time worked. Took us ages though to work through the non-understandable code without comments.
Colin Davies wrote:
This proves that the code initially accepted was not up to scratch.
I disagree. No system can be programmed at the outset to meet all future requirements. Businesses change and require new features in existing applications. Rewriting the app is insane, the business may only have changed slightly.
Colin Davies wrote:
Adding comments and attempting to make code understandable to third parties, just proves that you have no confidence in the future of your code.
Another facet is this; We work on many projects at once and trying to keep how each one works code wise in my head at once is impossible.
At times I will be phoned on a saturday night and asked to "quickly" fix something on a 6 month old project that has long entered the Recycly bin of my mind. Having readable code with comment-pointers is invaluable at 1am on a Sunday morning.
Paul Watson
Bluegrass
Cape Town, South Africa
Crikey! ain't life grand?
|
|
|
|
|
Paul Watson wrote:
Businesses change and require new features in existing applications. Rewriting the app is insane, the business may only have changed slightly.
No the spec and requiremnets have changed. This is no longer maintenance, but enhancement.
By now altering the original working code, you are actually as an analogy, placing an old modified part in a near new car.
This is neither good or fair for the client in the long run.
Quite likely this act of "maintenance" will introduce *bugs* into a good product.
Paul Watson wrote:
We work on many projects at once and trying to keep how each one works code wise in my head at once is impossible.
This is a real concern and a problem created by managemment, having a developer working on multiple projects simultaneously can only degrade performance.
Its like having all the car pieces in a garage as the workers work on cars thrown into one pile.
This is in effect what the management are doing with you.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
Its like having all the car pieces in a garage as the workers work on cars thrown into one pile.
Don't be so dramatic Colin, you sound like me.
Obviously I don't sit with three IDEs open trying to code three projects at once. What I mean is a developer is not going to spend a solid month on one project alone. In a perfect world this would be the case, but even I don't live in that world.
Anyway, you are trolling :P
Paul Watson
Bluegrass
Cape Town, South Africa
Crikey! ain't life grand?
|
|
|
|
|
Paul Watson wrote:
Anyway, you are trolling
Yes, I confess.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
How arrogant are you?
So you've never had to go back and change an application to meet new requirements? Suggests to me that was because it was never really used.
When an application is dependable and reliable it becomes part of a companies life and essential to operations and as business requirements change, the software needs to as well.
Re-usablility is crud! I have libraries that I regually drop into new application and can build a new CRM or PIM application for a company in about a week. WHY? because my crud is designed properly and works well 
|
|
|
|
|
LeeDaviesVBSource wrote:
How arrogant are you?
Very.
LeeDaviesVBSource wrote:
So you've never had to go back and change an application to meet new requirements?
Yes, I use to go back and make modifications etc.
But I have now learned that if my development was well organized initially it easier to just rewite segments or classes in their entirety. Maybe this as easier for me then other developers, as I seem to recall all the breakthrough stuff that was needed to be done the first time, and subsequent versions are just a matter of keyboard skills.
LeeDaviesVBSource wrote:
Suggests to me that was because it was never really used.
The royalty payments I recieve suggest businesses are still paying for stuff from a while ago. Unsure if they use it though. 
LeeDaviesVBSource wrote:
Re-usablility is crud!
I think you are misquoting me out of context here.
LeeDaviesVBSource wrote:
WHY? because my crud is designed properly and works well
Good.
So what's the point in commenting it !
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch ![Green Alien | [Alien]](https://codeproject.global.ssl.fastly.net/script/Forums/Images/alien.gif) "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
OK, Ok. So you don't believe in commenting. What about your documentation or don't you believe in that either?
I personally use .Net's XML documentation feature. Explain what the proc is supposed to do and return and if there is a problem with the function the new developer can just re-write it.
How about that for a compromise?
(P.S. You've started a good one here  )
|
|
|
|
|
LeeDaviesVBSource wrote:
What about your documentation or don't you believe in that either?
I believe in documentation !!
Ok first you should have the original requirements handy, sure you can add them with /* */ to the source code if you wish so they don't get lost, but visual requiremnets need to be on paper.
Also you should document what ever has been imported or used externally in the project||application. And of course if it's a team, who did what.
How the application or whatever was tested and what paramaters were used. (this is really useful)
Last of all how the Application and classes or libraries or whatever are to be used, so that you can have reusability of what is is good.
Since originally posting I have altered my mind as to commenting, and now consider that there are a lot of exceptions.
Understandable code is different as its got a lot to with ability and perception.
I have heard of professional developers that don't get *pointers*. Ok they manage to survive, but I'm sure when they find code that really uses pointers etc, they are befuddled.
I keep meaning to move to .NET, so until then I can't comment.
LeeDaviesVBSource wrote:
How about that for a compromise?
Cheers
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
If a solution is required, it doesn't matter if it is created in C++. C# VB, Pascal, Forth, Lisp, or Lego. What matters is if it meets the requirements of the client. Commenting and creating understandable code is a micro issue.
I respectfully disagree. I think it *may* depend on your range of experience, environment, level of co-workers (co-workers are often like your family: you can't choose them)
My experience says otherwise. I worked in a shop where we spent several years getting out from under several things:
Bad code design
Slapdash technique
Difficult to understand and maintain code.
There were times, (I sh*t you not) where what could have been done in 10 to 15 lines of code, had been done in 40 pages of code-- no comments.
No, difficult to understand code by itself is not often THE issue, but it can be a major factor. If I am doing a debug of a program, I don't step through every line of code. My employer couldn't afford it. I need to look at blocks of code, get the gist of what's going on, and eventually I'll zero in on the pertinent sections. Broad comments can help eliminate entire sections/functions very quickly.
If you've been lucky/fortunate to work in an office with highly compitent co-workers (or you work in a one man shop) readability and understandability are going to drop sharply on the list of 'must haves' because you're not speaking to a very wide audience.
Where I think your complaint can be legitimate, is corporations which get bitten by the beaurocracy bug want to institute some kind of hard line structure comments which end up taking as much time to puzzle out as the original code does. I can't agree more that this often becomes a process in and of itself thus causing you to add time to the top of the process that you cut from the bottom.
Comments or understandable code don't have to become a chore. IN the case of comments, a simple sentence can help eliminate a section of code.
//Get patient master record from database, parse.
And if the programmer is looking for the part of the code which prints the patient statement, he knows he doesn't have to puzzle out what's going on here, he can move on.
Is there a perfect system? Hell no. But I can tell you from experience, that our development time dramatically reduced once we added just a few INFORMAL practices. Again, we didn't move to some kind of god awful AT&T Bell Labs style UML IEEE documentation system. Just a few informal rules of thumb, and you can eliminate a lot of tripwires and traps in the future.
Paul
|
|
|
|
|
Paul Oss wrote:
Broad comments can help eliminate entire sections/functions very quickly.
Agreed !! with an additional emphasis on Broad.
Paul Oss wrote:
But I can tell you from experience, that our development time dramatically reduced once we added just a few INFORMAL practices.
I use to quite heavily comment stuff, and "refactor" code to be more understandable by peers.
To be honest I often find comments harder to understand then the actual code, and this includes my own comments.
Seriously I think when you are actually coding the perspsctive of what a later reviewer will understnd of the comments is influenced by your own mind state at the time. Thus maybe the best person to comment code is not the actual developer.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
To be honest I often find comments harder to understand then the actual code, and this includes my own comments.
Seriously I think when you are actually coding the perspsctive of what a later reviewer will understnd of the comments is influenced by your own mind state at the time.
No doubt that this can be the case. But that still goes back to the perfect world scenario. If you can't understand the comments, then you're back to square one and having to interpret the code- nothing lost. I don't think that I've ever lost anything significant by difficult to read comments, other than the fact that I will admit that the annoyance factor is high. I may not be losing time, but it makes my blood boil when I spend 4 hours going through nearly unreadable code only to find the comments annoyingly vague. I remember one of my favorite comments that was often made by a particular programmer... a comment I never really deciphered was (in an old version of a business basic (mainframe stuff)):
REM DO VAL SH*T
To this day, I never figured it out.
The only place where time can be lost by comments is when they're logically wrong. But in my experience this has been relatively rare.
Some of you may disagree with the technique, but when I suspected that a one line comment would leave more questions unanswered than answered, I would simply write a whole paragraph describing my reason for doing what I did, what the weaknesses were, where future problems could arise, and how future programmers might deal with changes-- and sometimes my thoughts and feelings on the subject at large. And honestly, they were the most useful later on. Because yes, Colin, I do have to admit, there have been times-- albeit rare-- that I didn't know what my own comments meant.
Paul
|
|
|
|
|
Instead of //Get patient master record from database, parse., how about:
<br />
PATIENT_RECORD * pPatientRec = getPatientRecord();<br />
parsePatientRecord(pPatientRec);<br />
- Renault
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
