Programmers: How well do you comment your code?

[Descartes]

Or, I guess a more appropriate question would be, do you?

People always ask, "do you comment your code?" I now ask, why do you comment? My manager was more or less flabbergasted when I stated, "I comment as needed only." I made the argument that if I'm having to comment the fundamentals of the language itself, then whoever is looking at the code shouldn't be touching it anyway. I also put forth the argument that in certain languages, comments can be extremely harmful. I can't tell you how many times I've found comments that were completely outdated, and didn't reflect the actual behavior of the code in question. This gives a false sense of security in comments. Also, I /constantly/ see comments in code that are almost exactly the same as the code itself! If a programmer has trouble understanding the basic fundamentals of the language, or programming itself, no comments are going to help him. Recently I was maintaining a project written recently that had calls to SleepEx() scattered throughout, each time with what seemed like a completely random number, and no comment indicating that the programmer chose this number for a reason. Comments would've been good, but "hiding" these magic numbers behind a symbolic constant would've better, imo. It would have at least told me that he had put some thought into it rather than hitting random numbers on his keypad.

Lets also consider the fact that, often, documentation external to the code itself is often needed. So much for orthogonality. If the code changes, you have to change the comments. If the comments change, you have to change the external documentation. In more modern languages (like Java w/ javadoc, and some .NET languages (C# at least) w/ XML documentation) this is largely eliminated.

Sorry for the long post. I'd be interested in hearing some opinions on this. Obviously the need for comments in C, or C++ is probably greater than say in Java, VB, etc., but the same idea applies to all. Are the days of transposing PDL directly to code gone, and if so, why do people feel self-documenting code needs to be further documented?

 

[Electric Amish]

Yes I comment, probably a little excessively. Especially since I try to use the Hungarian notation and descriptive variable names.

Your points are valid.

amish

 

[bunker]

Depends on if I'm working with a team on a project or if it's a solo project. On a team, I have to, solo, no way.

 

[RJHNY1]

I can't really answer your question, but I'm gonna answer a question with a question since we're on the same topic. My friend and I are both CS Majors. We both want to get into computers after college (not programming jobs), but WE DO NOT LIKE PROGRAMMING! We are taking programming classes b/c they are required as part of the CS Major. I took CS140 (java) last semester and it really wasn't so terrible. But this semester my friend and I are taking CS240 (C++). The semester is only 2.5 weeks old and the teachers are throwing programming assignments at us. They have barely taught us how to program using C++! We look at these assignments and don't have much idea what to do.

Does anybody have any web pages that can assist us in writing a programming assignment?

Am I correct when I say this...you do not need programming (or very little programming) once you get a job in computers after college?

Thanks for letting me vent and hopefully your responses can make me feel better.

 

[Rallispec]

i'm notoriously bad at commenting.. sometimes i'll write code and come back and look at it again a month later and wont even be able to decifer it myself.

 

[BigJohnKC]

We work with IBM's VisualAge for Java at work, at it automatically comments in javadoc style the creation date and author at the top of any new class. However, I never really cahnge these, so at the top of all my classes I have the comment "Insert the method's description here"

I usually comment a bit if the code is confusing or proprietary in some way, sometimes comment out old code, but not extensively like they told us to be sure to do in training. No one really comments everything, come on now....

 

[Jzero]

I've said it once and I'll say it again:
IF I WANTED YOU TO BE ABLE TO READ IT, I WOULDN'T HAVE WRITTEN IT IN CODE!

 

[Descartes]

<< I can't really answer your question, but I'm gonna answer a question with a question since we're on the same topic >>



This is ATOT, "off topic" is on topic



<< Does anybody have any web pages that can assist us in writing a programming assignment? >>



Tutorials in programming, or places where you can submit your homework and have others do it for you? "Do my homework for me" posts leave a noxious odor, and most people in newsgroups/mailing lists/etc smell it a mile away and do nothing but flame. Most people have no problem helping you to complete your homework, they just don't do it for you. Not sure if that's what you were asking...



<< Am I correct when I say this...you do not need programming (or very little programming) once you get a job in computers after college? >>



"Computers" is far too general these days. Everyone says they're "in computers", but that could be everything from data entry to using old computers to build coffee tables. Programming is only one facet of the vocational opportunities "in computers."

 

[notfred]

What do you consider "a job in computers"? Computer Science is basically a programming major. And Comp. Eng. isn't any easier. What do you want to do, plug in network cables and video cards all day? then get your MCSE and make $9/hr.

Anyway. comments. I don't use many of them, basically, I label where subroutines begin and end, so that they're easy to find.

 

[BigJohnKC]

<< I can't really answer your question, but I'm gonna answer a question with a question since we're on the same topic. My friend and I are both CS Majors. We both want to get into computers after college (not programming jobs), but WE DO NOT LIKE PROGRAMMING! We are taking programming classes b/c they are required as part of the CS Major. I took CS140 (java) last semester and it really wasn't so terrible. But this semester my friend and I are taking CS240 (C++). The semester is only 2.5 weeks old and the teachers are throwing programming assignments at us. They have barely taught us how to program using C++! We look at these assignments and don't have much idea what to do.

Does anybody have any web pages that can assist us in writing a programming assignment?

Am I correct when I say this...you do not need programming (or very little programming) once you get a job in computers after college?

Thanks for letting me vent and hopefully your responses can make me feel better. >>


I program every day at my job. We wrote a java application from scratch, and it's going into production next month. I guess it depends on your job. If you choose to go the IT route you'll probably be stuck answering phones all day, talking to stupid people with asinine questions about their PCs. If you go into the hardware game, you can probably build computers, but it won't pay as much as a programmer. I'm sure there are CS jobs where programming doesn't take place every day, but you'll be hard pressed to find them. But that's just my opinion, I don't know for sure...

 

[InfectedMushroom]

I tend to comment my code in the following way:

A few lines of comment before each function that tell you what the inputs are, what the outputs are and what it is supposed to do. That is generally more than enough for me to read someone else's code and I expect that it is enough for most ppl that are familiar with the programming language to be able to modify the code.
I also keep my variable names descriptive and always indent.

 

[Descartes]

<< I usually comment a bit if the code is confusing or proprietary in some way, sometimes comment out old code, but not extensively like they told us to be sure to do in training. No one really comments everything, come on now.... >>



Exactly. It seems for so long everyone subscribed to the mantra, "must comment your code." Many people comment because they feel it's some programmer imperative, but it's really pointless in many cases.

 

[Cerebus451]

First, I comment my code whenever I can. Especially if I had to think about the logic of a section of code first. It always helps when going back through code to have comments that lead into the mind of what the programmer was thinking when the code was written. I also write code that is always run in batch mode, and as such must run in the smallest time frame possible. Efficient C code and well-written C code are mutually exclusive, so I try to comment code that was obfuscated for efficiency purposes wherever possible.





<< Am I correct when I say this...you do not need programming (or very little programming) once you get a job in computers after college? >>


Ummmm.... If you are getting a degree in Computer Science, then all you will do is programming. If you want to work with computers, but not program, you are in the wrong degree program. Computer Engineering (though they sometimes end as programmers) or a more generic IS degree is what you should be persuing. The programming for a CS degree is only going to get worse for you.

 

[Electric Amish]

<< I label where subroutines begin and end, so that they're easy to find. >>



heh heh... He said subroutines...That's a PERL programmer for you...

As for the C++ problem, did you not learn C already?? C++ , and basically all other languages, are just new ways to do the same old things. I feel that programming is useful for all aspects of computer jobs. I think you better understand how computers and software work if you've dug into it a little.

amish

 

[CSoup]

<<
Am I correct when I say this...you do not need programming (or very little programming) once you get a job in computers after college?
>>



What do you mean by a job in computers? At my school most people who did CS or EE but did not have the skills to work in the software/hardware industry went on to do consulting or investment banking. Some consulting work might require computer related work and a little programming (i.e. e-business and IT consulting). Programming is basically the conversion of algorithms and processes into a form that can be easily translated into machine code. Alogrithms and processes are essential parts to a CS education (you will learn and use these in classes like Data Structures, Algorithms, AI, and most other CS classes), so you should think really hard about whether CS is the best program for you. Here is an analogy to put things in perspective. A programming language is similar to any other language, including English. It is a set of words with syntactic and semantic constraints. The set of rules is small, so learning it is not hard. The hard part is to apply the language to do something efficiently and correctly. This requires development of algorithms and processes that are then translated into the programming language. For most small things, people either have the algorithm already or just create it on-the-fly. This is the hard part, and the part that many people fail at learning. It is like writing poetry and stories in English which requires thought and time.

 

[NeoMadHatter]

<< i'm notoriously bad at commenting.. sometimes i'll write code and come back and look at it again a month later and wont even be able to decifer it myself. >>



me too. so do many people. commenting is like a chore no one wants to do it.

 

[StageLeft]

I hardly ever comment. Merely extending the same thanks to those who came before me and didn't comment also

I definitely appreciate comments and I have yet to see something over commented. In fact I hardly ever see anything adequatly commented. I do find they help so that I know whats going on quickly.

Basically the last time I remember commenting anything was when I had something weird going on and I knew that somebody looking at it would have spent a while figuring what was going on so I commented to make it a bit quicker for them. I threw in a good 2-3 lines

 

[Keego]

I comment too much

 

[notfred]

<<

<< I label where subroutines begin and end, so that they're easy to find. >>



heh heh... He said subroutines...That's a PERL programmer for you...

As for the C++ problem, did you not learn C already?? C++ , and basically all other languages, are just new ways to do the same old things. I feel that programming is useful for all aspects of computer jobs. I think you better understand how computers and software work if you've dug into it a little.

amish >>



Subroutine is a cooler word than function

 

[Sir Fredrick]

I'm converting some complex matlab code to c++, and guess what - it's barely commented at all. They're working with matrices that have up to 6 dimensions, and there is no indication what they are intended for, their use is scattered throughout the program.
I could probably write the code in a more efficient, c++ friendly way if there were sufficient comments about what they were trying to do. Instead, I am trying to emulate their code line by line (which also means that I'm using lots of nested for loops) so that it produces exactly the same results.

You can bet your monkey ass that I'm commenting my code very well. It really helps with the readability, and it can help you catch errors if you're looking at someone else's code: if I'm getting weird results with someone's code, and a comment says one thing, but the code actually does something else, that's a good indication that the error is on that line.

There are always some blocks of code where you'll look at it and wonder "why is he doing that?" - comments should answer that question.

 

[Danman]

I don't comment a lot because I am the only one reading the code.

 

[Queasy]

Since my job requires me to maintain code and do bug-fixing on a constant basis, I ALWAYS comment code so that I can track changes and anybody that reads the code after me can see that changes that have been made.

One of my former co-workers was pretty hilarious with his comments. He was a Brit and the best C++ coder we had in the office. Anytime he was asked to fix code, he would leave comments like "This code here is utter crap." or "I don't know what this idiot was thinking." or "I'm surprised this made it past QA...oh, we don't have a real QA do we?"

Classic stuff

 

[DaveSimmons]

For code inside functions, I comment anything tricky (then ask myself whether it can be done more clearly / cleanly) and also the beginnings of different "steps" or "sections" within the function.

I agree with others that comments like
count++; // add 1 to count
are a waste of time and make the code harder to read, but any "magic numbers" like the SleepEx() values Descartes mentions either need to be commented or better still replaced with a #defined value or class constant.

 

[RJHNY1]

<< Does anybody have any web pages that can assist us in writing a programming assignment? >>



Tutorials in programming, or places where you can submit your homework and have others do it for you? "Do my homework for me" posts leave a noxious odor, and most people in newsgroups/mailing lists/etc smell it a mile away and do nothing but flame. Most people have no problem helping you to complete your homework, they just don't do it for you. Not sure if that's what you were asking...

Descartes, I never asked anyone to do my work. I said to ASSIST in helping me understand. I don't want to write a program and have no clue as to what I just wrote. I really want to understand. This semester, there is a new textbook for C++ and there aren't many programming skelatons to look as a reference or model my programming assignment after. Also, what I mean a web page to assist is like a little tutorial to help me LEARN C++ better. As much as I would like for this class to be a history, I want to learn something in it too. My teacher is the dept head and I'm a little pissed off b/c they don't teach us much code or how to write a program. Mainly, they just go over terms. That's easy...just read the book. I read the first 2 chapters and while I understand terms like pre/post conditions and try/catch/throw, etc, I don't understand how to program!!!!

 

[Elledan]

About 3/5th is comments, the rest is code.

If you ever want to know what the hell you were thinking when you wrote that piece of code, you'll have to comment it. Excessively.

<--- is speaking from experience.