Who still puts comment in his/her source?

[nick]

I'm a last year student, and I have worked with progress (8.3 and 9.1) ... to make our application 'maintainable' we put in lots of comment (even a six-year old can find out what our application does )

We've made it a good habit to put in a lot of comment, but now we are wondering how many of the 'more experienced' programmers still put in lots of comment.

Or is the idea after a few years of programming : 'Good luck if you try to adjust something after me'

 

[jamesmc]

I have been programming in various languages over the last few years and my attitude is that when I am modifying code I would want the original author to comment their code so I can understand at a glance, so why shouldn't I comment my code and help someone else out in the future?

I generally load my code with comments starting with a header detailing the function of the program, author and any modifications that have been done. I also comment out (not remove) code that shouldn't be run anymore and put revision comments against code that was changed or added since the release date.

I have looked at COBOL code that is pages longer than what I would class as a long Progress program (I'm talking nearly one hundred pages long!) and it is a god send that it has comments.

Besides, comments are stripped out at compile time anyway so it makes no impact on the r-code size, why not pack it up with comments. Have you ever come back to work after a two week break, looked at the last program you were mod'ing and thought 'what the hell is that bit there doing?' comments aren't just for others to make sence of your code, they are also for authors too.

James.

 

[mra]

Hi Nick!

Comments are a must - no doubt about it!

Or, prober comments because code with unnecessary or incorrect comments can bee even harder to read than no comments at all. Personally I hate comments like "Now I'll save my values in the database' or "Save value x in y". You should comment on the logical flow of the program, and not how the code is written.

Some kind of standard in comments should also be encouraged.

I've been around for more that 10 years, and I comment more than ever (But maybe that's because my memory is not as good as it used to be ).


Regards
Mike

 

[AVV]

Hi Nick,


i guess the answer should be:
'Shoot the guy not commenting his changes'.

Programming and comments will go hand in hand till the end,
at least they should.

Programming Experience almost 25 years and not even close to retirement

AVV

I'm a last year student, and I have worked with progress (8.3 and 9.1) ... to make our application 'maintainable' we put in lots of comment (even a six-year old can find out what our application does )

We've made it a good habit to put in a lot of comment, but now we are wondering how many of the 'more experienced' programmers still put in lots of comment.

Or is the idea after a few years of programming : 'Good luck if you try to adjust something after me'

 

[dchatfield]

Always put comments (even if seems simple). What may make sense to you today may not make any sense 3 years from now (I know this from experience ). I also believe it is just plain common courtesy..

 

[santhosh22s]

Hai,

Iam in this programing field for the past two years, and now currently working in progress.

But wer ever it may be i follow putting comments in the codes as a good programming practice.

Even if some one touches the code in future wen u are nt there, he shuld know the code.

so its always good to use comments.

 

[FrancoisL]

I won't Comment on this thread :lol:

 

[joey.jeremiah]

I know I'll get pounded on this ...

but I'd like the question to be, how much ?!

What to comment about or what's necessary ? for almost every single line, that you're likely to see in the code PSC publishes. Or just reminders why a procedure has to work in one way and can't in another, abstract explanations about a process or idea where it's needed and isn't self explanatory, that you're likely to see in my code.

I don't think you'd want to dump the entire technical specs in the code. Not that I personally write technical specs. I only write functional specs and even that is only for none trivial jobs every once in a while.

Personally, I try to comment where I feel it's necessary but it really is hard, at least for me, not to mention time consuming. Writing in English and writing code are two very different skills, I really envy people that can.

It'd be interesting if someone remembers any worth while articles on the subject. I hang around @joelonsoftware.com quite often don't remember any articles like that.

I don't want to sound like a snob but most code I run across written by someone else are usually these horrible spaghetti code with thousands of patches that somehow still pull together, I'd be lucky if it's even properly nested, forget about comments. And most of the time I prefer writing the procedure from scratch, it's just quicker that way and a hell of a lot better.

Anyone that has worked on MFG/Pro would know what I'm talking about. QAD are one if not their biggest partners, I think, they're the biggest single reseller. It's not just that the code is a ****ing mess, we have these talks about code being elegant, it's a miracle it's even running.

Progress has been talking for years on how to build application and architecture etc. and QAD, probably, their biggest partner is the perfect example on how not to write code.

 

[Casper]

I saw attempts of programmers to write complete essays in there code. So I think overcommenting isn't very helpfull aswell.

I put comments in the source so other programmers can see the flow of the more complex parts of a program. And for clarity sake I put a comment after end statements if they span a large piece of code, so people still can see what end ends what .

In my opinion comment should be functional so no comment like:

.....
else do:
  /* the program shouldn't come here */
end.
 
or 
 
then do:
  /* there should be some kind of error handling here */
end.
 
or 
then do:
 /* for future use */
end.

From wikipedia:

1. Don't document bad code – rewrite it (The Elements of Programming Style, Kernighan & Plauger).
2. Good comments don't repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do. (Code Complete, McConnell)

Cheers,

Casper.

 

[joey.jeremiah]

Hello Casper !

Great to hear from you.

I haven't decided if I'm going to PTW yet, are you going ?

Cheers

 

[Casper]

/* Yep I'm present there. This year its almost next door */
/* Would be nice if you could go there too..... */

 

[mpowell_esq]

A shop that DOES NOT remark their src code is pants. Remarks / comments are for a reason. Just because a developer creates some code, it does not mean that same developer will maintain the origional src a period later. Organizations should MAKE their development team use remarks. Whilst learning to program, comments / remarks seem boring and useless though on the shop floor - in the real world - how are you supposed to know what somebody was thinking at initialization?

 

[sphipp]

If you use meaningful names for procedure, functions and variables then programs tend to self-comment. This removes the need to comment everything.

But, where something is perhaps complicated, not clear or does something that affects something else, then comments are essential.

Headers and end of program comments are also useful, as are modification comments.

As someone who has been using QAD for 6 months after programming in Progress for 12 years, I must agree that their writing style and code is absolutely awful. It's almost as though they've made the decision to make their code so complicated and hard to follow that nobody will be able to use it in other programs

But, there again, I am a programmer and they are a multi-million dollar business, so who's right?

 

[Lu-Tze]

I am very much in favour of relevant comments (with the stress on "relevant"). My code contains comments to:

• clarify functional requirements that cannot be readily deduced from the code (e.g. arbitrary decisions on how the code should behave);
• explain my choice of one technical solution over another, if more options are available and there is a clear reason for that choice;
• add technical comments but ONLY if there is a danger a collegue would erronously "correct" my code: some of my co-workers have a tendency to apply our internal programming rulebook to any line of code they see, and will happily add "NO-UNDO" to any variable definition they see, even if there's a reason why it isn't defined as such.

All you need for relevant commenting is a bit of programmer's empathy (if that's a term): if for whatever reason (EXCEPT lousy programming!) you or someone else might not understand what is going on in your code, it needs a comment.

First post after a long time of lurking by the way. So: hello all!