Hello.  I want a site that displays or have professional source codes.  I've been programming in C++ for a while and I just want to see how my programming is different from professionals.  I want to see how they document their programs.  I'm not sure if I am doing to much documenting or too little.  Please tell me of a place where I can find out.  If you know a site that teaches how to comment a programming document please tell me.

~thank you
Who is Participating?
SunBowConnect With a Mentor Commented:
Agree with above, professional coder will not translate to professional documenter.

For web, try searching for source code links and when you find one that looks 'professional' keep it around and try its method on for size.

I like to lay out in blocks. Lately it goes, lots of lines up top to give the overall gist of what's going on, what's coming in, how it relates.

I like very limited comments by line. Too often they place a 'cloud' over the real action. But I like their supportive nature over time, I be forgetful.

I think 'modular' coding is best, so I also comment as module leads off, and sometimes as it ends if the current state is worthy of note.

Hmm I'll repeat: Is it worthy of note? If not - do not comment. Code can be self explanatory. Use of good clear variable names. If the code is readably clear, any comment is over-comment.

The code should stand out to you on its own regardless.  I sometime design around screen size (editor) but if code is lengthy, and printouts are of value, consider page breaks and comments that can make it to top of page to let you know where in program you are.

If you have numerous programs all in one package, another technique is to boilerplate the front end.  The comment strategy, layout design of each program MUST look same from one program to next or it can never be 'professional'.

The boilerplate polish of front end includes the likes of these informational items:

Name, date created, by who
Project/function - description of what it does
What is coming in
What is going out
A precoded section for future comments

This is basically to preestablish ground rules for updates to use comment format that complies with the general boilerplate idea. If this is to be a one-liner, it could look like 'date', 'updated by', 'description/fix'. It can include a tag, a #, that can be utilized in code below to indicate which modules where changed for that particualar 'enhancement'. I find the date itself is sufficient.

It all depends on needs of the code itself and what coder needs.

So professional means, from one program to the next for this project,

1) programmer can use same method to find information from comment section

2) programmer unfamiliar with the program can FIND the code that needs update fix without the comments obscuring the search

3) same programmer, upon finding code that is not clear on its own, has easy method to clarify through comment design

A lot of this is very visual and very dependent on what the code does, whether it does so using obscure techniques, or very straightforward techniques.

Lest I forget, I 'assume' that you already are aware, that the code layout itself, with appropriate visual layout is also professional comment. Use columns to align, and indentations to group, that kind of visual aid is in itself professional commenting on what the code is doing. Keeping loop constructs in similar layout from one section to the next.

Many books with sample 'free' CDs come with what THEY think are professional commenting.  You surely must have one, try one on that is unfamiliar. Look to see if it looks professional to you now. Can you really read it and could you easily find how to update it?

Apply same to strange new code on the web.  If they visually support reading & updating, and do not get in the way, then they cannot be that bad, right?
I think you might be disappointed.

Anyway, one good place is
Jan LouwerensSoftware EngineerCommented:
yes, I agree with jhance, "professional" coders rarely document their code sufficiently enough... I think they use the term "job security" to rationalize this behavior  =)
Keep up with what's happening at Experts Exchange!

Sign up to receive Decoded, a new monthly digest with product updates, feature release info, continuing education opportunities, and more.

The poor state of program documentation is typically a sign of arrogance (and/or laziness):

"I know what this obscure coding does.  If you can't figure it out, well, that's your problem for not being as good as I am.  Moreover, my time is too valuable to waste on comments.  Besides, we all know that nobody bothers to change the comments when they change the code, so why bother."

The seasoned, mature programmer knows that six months from now he'll have absolutey no idea why he did some cutesy little thing, so he uses comments as future reminders:

"I may know now in the heat of the battle that CurrFilePos is a global, but when (not if) I come back to enhance this dog next year I'll have forgotten that.  Maybe I had best leave a little reminder.  While I'm at it, I'll make a note that it's set over in LoadNextRec."

Rather than ask yourself if your commenting is enough or too little, you should ask yourself if your commenting is sufficient to understand what and how the program does what it does.

For some high quality commenting, check out:
"job security"...ehh? Others can't read it they can't edit it, they can't edit it you still have a job as the boss man/women needs ya around

This is the beauty of "open source" as well.  A company can claim to be supporting the open source movement but still nobody can make heads or tails of their software.  Take Netscape and "mozilla" for example.  That is about the most incomprehensible excuse for source code I've ever experienced.  It would be easier to understand if they had run it through an obfuscator!
Remember, if you can't be replaced, you can't be promoted
DVB, If you can comment code on demand, you can be promoted :)
Question has a verified solution.

Are you are experiencing a similar issue? Get a personalized answer when you ask a related question.

Have a better answer? Share it in a comment.

All Courses

From novice to tech pro — start learning today.