I am one of the old people in this business starting out in 1970 with Assembly language and going through COBOL and into Microsoft products currently doing ASP.Net Version 4.5 today. In the past I have always thought that the code was not finished until you had it well documented with comments for the programmer(s) that came after you. That was until I took up my current job and have a boss that does not think that comments should be put in the code and that if you wanted to know what had been done before you always have the source code history; with Vault or Kiln. I have been seeing a lot of code that we go out and look at on the Internet that does not have comments in it. My question is do you use comments in your code?

Yes, and IMO it's as important as running a repository. If I find an undocumented routine later, and I have to think more than 10 seconds about what it does, I document it.

For more complex routines, I tend to write the code by starting with comments that represent what needs to be done, and then writing the code around those comments, preserving what makes sense.

I also write lots of code as libraries, so I use the XML commenting system for subs and functions in those since you get the added benefit of comments / instructions in Intellisense when calling that library later.

That being said, if Kiln provides a full commenting system for the code, that's available as part of the repository, and that everyone uses, it may make sense to use it. My only fear with having comments in the repository is that the comments are dependent upon that particular brand of repository, and if management later decides to abandon said tool, then all of the comment system goes with it, instead of staying with the code. I also like the idea of having comments in the code so that as code changes, and comments change, you can see that as part of the code history, and in things like Blame.

I come from the same era as you do. I wouldn't dream of leaving code undocumented. I do it for my own protection as well as those who come after. It is often not apparent what the purpose of a piece of code is or how it is intended to function. Comments are essential and time-saving. Maybe if all maintenance involves scrapping what you have and starting over (with the last working version from the archive) you could justify. I doubt the economics would bear that out.

Answered

Sorry! Something went wrong on our end. Please try again later.

smunk

September 05, 2013 11:53 AM

I have always appreciated when the developer before me includes well
written and thought out header and inline comments in code. This is
especially important when the code includes complex formulas where the
variables involved, and/or the result may not have an apparent meaning to
another developer. The assumption that ""this is perfectly clear to me, so
the next person should know what is going on"" may not apply in reality. I
have even seen developers intentionally obscure their code in an effort to
bolster his or her own position.

From a management perspective, failure to support good/clear documentation
and commenting practices is just short sighted. This often comes out of
pressure from above to turn solutions around faster than can reasonably be
expected. The problem with this is that lack of documentation leads to
longer turnaround times in future maintenance. So in effect, we save an
hour now, only to spend four later on.

On the other hand, if you are commenting out deprecated code rather than
deleting outright, and you are using some sort of version control, I would
have to agree with your manager that the repository is your resource for
historic code, and there is little need keep outdated code commented out in
live code.

I try to make my code understandable because at my age (within days) you have forgotten what it was meant to do.

I mainly achieve that by using meaningful naming conventions for controls and variables.

Also if it is a toss up as to elegant fast code versus easy to understand code, easy to understand always gets priority.

If something is complex and otherwise might be combined with other complex code, I will strip functionality out into Subs and Functions, which are easily comprehended.
Most times all of that is sufficient to make the code understandable.
And when it is not, only then I will add a comment.

Rob

Answered

Sorry! Something went wrong on our end. Please try again later.

Michael Meyers-Jouan

September 05, 2013 12:12 PM

In assembly language, we used comments extensively (the equivalent of a single statement in a high level language was a series of instructions), and we also used comments to document changes in the code - because we didn't have source control applications.

In high level languages, such as C#, that have some way to identify (and preferably to collapse) blocks of code, I use the pragma to insert ""pseudo-code"" that should be enough documentation to understand the actual code. When a block has a series of nested blocks, the pseudo-code illustrates the implementation of the outer block.

The only time I use actual comments is to document something ""not normal,"" such as: an ""abnormal"" sequence of statements that has a specific reason for being; or an algorithm that most programmers won't find familiar. In other words, anything that the programmer who maintains the code really needs to understand.

If you're using a source control system, I agree with the policy that changes in code should not appear as comments. One major reason is that it makes the source code far longer, and therefore hard to understand.

I'm of the same Vintage as sjoToolbox, but I completely agree with Rob Lee on this.
I especially agree with his style of putting comments before the code - it keeps your
logical thought process in place. Even after I've had a coffee break!! Or, more likely,
after my aging body has demanded, a break of another nature.

Have Fun,

James O'Brien.

Answered

Sorry! Something went wrong on our end. Please try again later.

0Name

September 05, 2013 12:29 PM

I'm an old time programmer too.
I don't do line comments much anymore, but I do at certain places - the
endif/enddo etc get enough of the original IF/DO so that it's easy to
recognize what's being closed. I do heavy breaks outs on ""paragraphs"",
though - each paragraph of code will get a heading -- eg
------------------ INIT --------------------
---------- Validate --------------------
--------- fetch data -------------------
---- (etc) --------------------
------------ Clean up and exit -------------

and within that, will be as many blocks as necessary to break out each
""thought""

I absolutely DEMAND header blocks, though - the function name, what it's
for, who worked on it and when and why. I've had more than one cyclic
problem where the logical solution to problem A caused problem B to come up
a month later, and then the logical solution to problem B caused problem A
to come up a month later. It wasn't until you could see the edit history
for that subroutine that you could catch what was going on and come up with
solution C that dealt with both A and B. Not to mention, one of the
fastest ways to search for new bugs is to search for recent edits.

Lastly - I find that people label their code (and therefore have to block
it out) are more aware of of how they process through a module.
Undocumented code tends to be ""hack at it until it runs"" and it takes hours
to figure out what they're doing, not to mention tasks are done poorly and
(frequently) repetitively.

No, I don't comment my code because I don't work with others. Good code should explain the logic and purpose themselves clear. There is no need to comment the bad code. Comments are for non-programmers or bad programmers. They just read the comments and still don't understand the code. In 70's programming languages are too new to people. Lots explanations were required at that time. Now many kids can understand the code better than comments. Coding standards are more important than documentation standards. That's what I think.

Answered

Sorry! Something went wrong on our end. Please try again later.

Shiraj Ramachandran

September 05, 2013 12:52 PM

I really come from the so called new age. Commenting code is certainly not an optional practice, and whoever against coding is basically lethargic. In fact to add on to this, I insist on additional documentation such as capturing DFD, CFD, ERD, LDS and even State Transition diagrams.

No, I don't comment my code because I don't work with others. Good code should explain the logic and purpose themselves clear. There is no need to comment the bad code. Comments are for non-programmers or bad programmers. They just read the comments and still don't understand the code. In 70's programming languages are too new to people. Lots explanations were required at that time. Now many kids can understand the code better than comments. Coding standards are more important than documentation standards. That's what I think.

You're a relative youngster. I wrote my first piece of software in 1964. My opinion is that if you use meaningful variable names and function names you only need to
comment those pieces of code where the function is not absolutely clear. Whenever I've had to debug someone else's code I always look at the code first because I
have found that ""header information"" tends to lose its accuracy over time.

Answered

Sorry! Something went wrong on our end. Please try again later.

Shiraj Ramachandran

September 05, 2013 01:55 PM

The notion of good and bad programmer is highly relative. Its definition could change instantly based on change of perspective.

A successful code should be repeatable and objective, so that it is person independent. Then on the code carries commercial value and meaning. If these conditions are met, usage of undocumented code is always a disaster and would never be accepted in the corporate world.

Regards,
shiraj

Answered

Sorry! Something went wrong on our end. Please try again later.

Michael Meyers-Jouan

September 05, 2013 06:03 PM

@llorracj,

<I have found that ""header information"" tends to lose its accuracy over time.>

One of the reasons that I like C# is that, in Visual Studio, the compiler generates warnings if the ""header"" comments don't at least match the procedure declaration (the names of all the variables).

I think you should listen to your boss. Your boss wants you to concentrate on coding since you are very experienced developer. He/She can always hire someone else to add comments in.
p.s. many decades one of my old bosses assigned a senior programmer analyst and an assistant to do the dirty jobs for me because programming language was my second language and English was my third.

Good comment. I don't against using comments but they should be done by someone else. No one can maintain my code if no one can put in the comments. A disaster can still happen even with well documented code. Only bad code can cause a disaster and comments cannot prevent it happens.

Well I hate to say it but in every software engineering class I ever took and every corporate engineering project I have been involved with, ""good programming style"" not only includes well documented code including comments around revision history, but it also includes another frequently overlooked unnecessary practice of consistently using a tabbing style of indenting code contained within blocks of code like FOR loops and IF...THEN code segments. Both indenting and comments are not necessary for a good program to run but they are indicators of programmers that are cognizant of having other people read and understand their code.

Of course you put comments in your code, might inflate the text file, the
compiler ignores it
I even have trouble with my own code without comments

I'm guessing your boss has never or has very little code experience and has
become a manager for some weird political reason

I could use a bit stronger language, choose not to, put comments in code if
you or anyone else wants to use it again,
and use variable names that mean something, at least to you

Answered

Sorry! Something went wrong on our end. Please try again later.

Dirk Byrd

September 05, 2013 11:58 PM

You get much repeat work?

Answered

Sorry! Something went wrong on our end. Please try again later.

Dirk Byrd

September 06, 2013 12:04 AM

No, the boss can't ""ask someone to add in comments"" only the coder has the
time to add comments, and ""always listen to your boss"" not sure where you
live, or the color of the sky, they hire me to make decisions on my own

Yes, I did get repeat work but I am already retired. I have not given up my code writing yet. Now I can still improve my coding skills and come up better code than before. Thanks for the programming blogs. Note:I started to program Fortran IV in 68.

Comments are quiet important when a complex algorithm is used in a solution. How at times comments can unnecessarily blot your codes. Modern languages have became quiet explicit making us more and more lazy in documenting. Its good practice as a programmer to document your solutions because ideally if you were to come back 15 years later to your source code you will be equally baffled as to what you were trying to achieve if there was not proper documentation. I experienced the same thing when I was working on a Barcode algorithm that I wrote in VB 5 some time back and wanted to copy the solution and translate it into C# last year because I wanted to embed it it my new project. What was 50 lines took me a hell lot of time to figure out because I have become so much embodied with C#. I did not comment the source code that time.

Dennis

--

Answered

Sorry! Something went wrong on our end. Please try again later.

Shiraj Ramachandran

September 06, 2013 04:39 AM

Hi Dennis,

You are extremely right on this. The problem is the way Microsoft is trying to carve out the new generation - its a secret but well known agenda - disregard software engineering principles basics and run behind the virtual platforms they create - hence they produce technical resources who are permanently tied up to a particular IDE or interface for programming and hence discouraging creative attitude towards programming. Of you are really a good programmer, you should be able to use one language with equal use as compared to any other. For example I was a hardcore fan of C++/Java where it just took me not more than one week to master VB6 with equal expertise - same when I learned perl script/php/LISP. This is possible only when your programming principles and software engineering base is strong. And Microsoft doesn't want this to happen - it a simple commercial battle and our programmers community is clearly falling victim to it.

That's just crazy. Code comments are not for what changed but why something is implemented the way it is and what exceptions or bugs are being avoided. At FMS, we follow a rigourous commenting process that has helped us maintain code for over a decade. It's critical for developers to leave good comments so future developers can mainain the solution more easily and safely. That future developer may be YOU.

We do these steps:
1. At the procedure level, we note when it was created and by whom (developer's initials)

2. When the procedure is modified, we add a line with the date, whom, issue ID if it's in our development log, and a one line comment on why (not what) it was changed.

3. At the module level, we note when it was created and list for each modification, the procedure name and the change. That provides a nice summary across the module to see what was changed and it makes it easy to understand when multiple procedures were changed at one time.

4. At the project level, we keep a list in a module (where we store our global variaables) of all the changes noting the module name, procedure name, etc.

The investment in good commenting is a basic Best Practice and pays off in projects that need to be maintained over time.

Sorry Dirk, I was no coder. I have been living in SF Bay area for the past 34 years. A few miles from Apple. We have the best weather and lots high tech companies here. I saw the changes in the Silicon Valley. I saw the dot com bubble. I saw the housing bubble. Many building signs changed in every 5 years. From NonStop Tandem to Compaq to HP to Apple. Some companies layoff all the staff sitting in the cubicles every 3 years when project phases changed. Comment or no comment made no different for those people. I was one of the lucky ones who had office, not cub during those years. Sorry everyone I am off the topic.

Answered

Sorry! Something went wrong on our end. Please try again later.

Michael Meyers-Jouan

September 06, 2013 11:48 AM

@ sjoToolbox,

As I follow this thread, I keep coming across ""interesting"" points.

You mention you ""have been seeing a lot of code that we go out and look at on the Internet that does not have comments in it.""

There are two ways to interpret this statement:

? You are using the Internet to find Web sites that are open source code repositorys,

? Or, you are looking at the code embedded in Web pages.

If you mean the latter, of course there are no comments. The owner of the page has reduced the size of the contents to improve the speed of loading. In addition, pulling out the comments ""obfuscates"" the code - making it (slightly) harder for other developers to understand and hack.

There are lots of tools that enable a developer who has code with comments to strip out the comments as part of the process of ""rolling out"" a production Web site from a development version.

Michael S. Meyers-Jouan

Answered

Sorry! Something went wrong on our end. Please try again later.

Michael Meyers-Jouan

September 06, 2013 11:49 AM

<He/She can always hire someone else to add comments in.>

Umm - no.

The original developer knows (at least, if he/she is a decent programmer, he/she knows) what the code is doing, and can add meaningful comments. Someone else must take a lot of extra time to figure out what the code means before he/she can possibly add meaningful comments.

The original developer who doesn't add whatever comments are needed to make the code comprehensible to other programmers is not doing his/her job.

I totally agree with your points. You have a very good practice and your company will have a bright future.

The requirements for commenting are varied and can be different from routine to routine, program to program, project to project and company to company. Making the size of each routine smaller much less comments will be needed.

I can also give you two extreme cases about commenting. The laptop and the server that contained my well-documented programs for a company got re-imaged and returned to the leasing company after the company reorganization. On the other hand one of my programs that I developed in 1974 had no single comment in it but my boss and my world-renowned professor from the university you graduated from praised me and that program in 1997. Note: I just found about the information two years ago.

Hope one day we all can come up maintenance free software then no commenting will be needed.

p.s. having service manuals or service records are good practices but my old Mechanic Raul never needs them. Just like him I don't read the comments when I debug programs.

There used to be a joke around ""real programmer don't document. If it was hard to write then it should be hard to read.
Seriously I agree that code needs documenting. How much depends on the naming conventions used.
I admit to not liking documentation and usually do it at the end as when I am writing code I think in programming language and am so focused on the code, I need to get it entered without interupting my train of thought to document. But I do go back and do it. I also try to name variables, fields and controls with comprehensible names and indent code as well.
I've worked with those who write the documentation first and then code. Doesn't work for me. I guess it doesn't matter when the documentation is done just that it is. Not just for later programmers but also for yourself when you revisit the code. We need all the aids we can get as we get older :-)
Mary

Comment are of course a great idea especially for explaining why a function works the way it does or how it works etc. But one thing to do even where commenting might not seem so obvious is try to write self-documenting code. This was and is one of the great strengths of COBOL, the complaint is that it is so wordy the good news is, it is so wordy. Take advantage of good descriptive variable and function names and of course be consistent. Self-documenting though is still not a substitute for comments. Remember the guy coming behind you likely never attended any of the meetings regarding the program you written.

John Warner

Answered

Sorry! Something went wrong on our end. Please try again later.

Allan Mee

September 08, 2013 09:35 AM

Hmmmm I've always used meaningful variable names (apart from simple loop control variables such as i, j and n etc.)
But for general variables I use meaningful names and try to use a form of modified Hungarian notation naming - even to the point of indicating the scope of the variable - local or global, as well as its type and name (which hopefully helps to indicate its purpose).
I do in-code documentation - usually a brief explanation of what a section of code or routine does. I try to remember to point out the side-effects - even if just as a reminder (e.g. if a variable is passed by reference, then changing the value of said variable has [usually important to know] side-effects) - and global variables reduce information hiding [information hiding is usually a good thing]- but are often still the best/most efficient way provided you're aware of the issues.
So yeah I've always felt that some in-code documentation is necessary/useful - but overdone, it can have the reverse effect - actually making the actual code more obscure and easy to overlook details.
For example, if one uses the gets() and puts() functions in C, say, it's more important to do boundary checking (since C doen't do it) than it is documenting what the gets() and puts() functions are doing (I prefer using a self-written version of getline() instead of gets() as one can more easily control how much of the input is used/suitable before assigning it to the storage variable/array so as to prevent buffer overruns etc.) So I might add a comment as to why I'm using an in-line getline() function instead of using the gets() function. But I don't want to get into the vagaries and details of individual languages here - just used the C example as an example of what I'm [hopefully] saying.
Allan

Answered

Sorry! Something went wrong on our end. Please try again later.

Shiraj Ramachandran

September 08, 2013 01:28 PM

Dear all,

I've been curiously observing comments from some of the veterans in programming here on this thread. As a programmer myself, I can really understand your reasons for the insignificance of commenting. But when I had to move on from a programmer to a senior executive and started interacting more with real-world commercial scenarios and especially Project Management activities (that holds an SDLC together), I understood one thing - when you work with a team, all may not have the same caliber! Hence it poses major problems in your team maturity and team process if you don't follow common commenting standards.

And if a team that is intellectually rated as 'nominal' by the project management cannot handle a piece of code due to lack of proper comments, the code becomes project risk rather an asset even though the code might be elegantly written. It all depends in the mean IQ values of all team members to make a decision on this. Hence to be on a safer side, commenting is usually adopted as a best practice. Even though I personally don't like this concept, easily controllable code is more preferred than complex elegant code.

Don't forget the programs are written in universal programming language already. No words need for a great art. No comments need for great algorithms that written in an universal programming language. Only limited comments are an error free routines. Note: English comments are not universal.

Sorry All, I made you spend too much time on this subject. Anyway, it seems to me he wants to sell his boss extra or an extended warranty for his work. He can always put comments on his free time. Just tell the boss there is no charge for the comments.

Many programmers love to write fast and/or elegant code.
You can see them posting in our forum asking which approach will be faster.
In most of those cases, being fastest (or elegant) should not be an issue.
Instead they should be adopting a style that makes the code easy to read (see my earlier post - meaningful naming, and splitting complex code into separate Subs/Functions),
If they did that, then most comments would NOT be required. There will just be a few spots where comments are necessary.

It has always been ideal to include comments in the code itself, instead
writing in a separate document. However, you have to prepare a user
documentation pertaining to various
processes/features/capabilities/functions in the software system. Dr Sharma

Years ago, I was working on a project and I had a particular assigment that was to allow a user to select a range of numbers. They could select from a range below a certain point, above another point or the range between the two. So, all numbers could be in the range of 'A', 'B' or 'C' and they could only select from one range. (Or something like that - it was 30 years ago, in DataGeneral Basic). I spent all day - a long one at that, working on it and had an AHA moment after an hour drive home.

Anyway, the module was short, fast and seemed to be bulletproof. I put it in the library and promptly went on to another module.

One month later, I pulled up the code. I sat dumbfounded - I could not remember how it worked!

So, I put in a full page of comments for a 10-line function.

Yes, comments ARE necessary! Source Control has it's place, but it's not going to take the place of aptly placed comments around 'special' sections of code.

I have found that too much commenting is meaningless. But no comments
causes the person following to work too long on discovering was is attempted.

If the code is grouped together in appropriate subroutines. With each
subroutine documented with inputs, expected outputs, and comments on the
process is a great help. However do not use abbreviations in the comments unless
explained, e.g. I worked for a Security Software Company where LID stood
for Logon ID. When I moved to a Navigation Software Company, it took me a
while to understand LID meant a section of a road.

Answered

Sorry! Something went wrong on our end. Please try again later.

Michael Meyers-Jouan

September 09, 2013 11:12 AM

Recently, I had occasion to deal with a table using an ADO Dataset (and no, Rob Crombie, I'm not going to apologize for using Datasets - despite the problems I'm about to describe ;<).
My code used a DataAdapter to load the dataset. The code then modified one field in each record, and executed a Dataset.Update: according to the documentation, this would update the database table with the changes.
It failed. The documentation was wrong.
I changed the code to copy the entire dataset to a second dataset, which I could then use to update the underlying table.
To any programmer looking at the code, this would be an obvious bad design: inefficient, hard to understand, and just plain poor design.
Therefore, I add a comment explaining why this bizarre sequence was necessary.
While I don't, in general, add comments to my code (the variable names and procedure names should be sufficient documentation, given that the procedure structures are simple, using sub-procedures to isolate any complexities), I would hate to try to learn an uncommented piece of code with this kind of odd ""design"" - even if I wrote the code in the first place.

Thank you all for your take on whether comments should be added in to the code. What I've gotten out of all your replies is:

1. Comments should definitely be added to the code, especially when the code is doing something tricky.
2. Commenting out code to be changed is not necessary if there are people who do not lke it.
3. And I am going to keep on doing this form of commenting in my code.

I've never tried the DataAdapter/DataSet combination to update an underlying database, but I have used the DataAdapter/DataTable combination extensively to update
an underlying database. I'd be interested to know what problems you encountered. I know the rules for success are less than clearly stated in the documentation.

Just remember writing good code at first place and then adding good comments to explain our good work. Comment or no comments make no difference to the compilers, debuggers and me.

p.s. two days ago I needed a topological sorting routine in VB6. It took me a day to find one of my ""The Art of Computer Programming"" books which I kept for the past 40 years. I got vol 3 but the algorithm wasn't in there. It must be in Vol 1 that I haven't found yet. It might take a couple of hours to rewrite one even I found that book. I searched the web and found the solution at http://rosettacode.org/wiki/Topological_sort . It contained the code in more than 20 programming languages. Some were with comments and some were not. I supposed to pick the VBScript one or VB .NET one. Those ones had comments but I picked the Fortran 77 one with no single comment. A few minutes later I had the VB6 routine I wanted. Thanks for the article. Please take a look at that site yourself to see which one you will pick.

If you have the vol 1 of Knuth's books please tell me whether the algorithm was there.
Thanks.

The TSORT routine that I mentioned above should be an example of a maintenance free routine. There is no need for the next programmer. We can continue use it and no change is needed. I don't even know how to add any comment into the code section, do you?

Answered

Sorry! Something went wrong on our end. Please try again later.

arbert

September 10, 2013 01:21 AM

The original question was ""My question is do you use comments in your code?"". Is TSORT your routine? If it's a third-party routine/DLL/ASM/etc, it makes it kind of difficult to comment. However, you can definitely comment YOUR code where you call and utilize the routine.