Want to win a PS4? Go Premium and enter to win our High-Tech Treats giveaway. Enter to Win



Posted on 2000-04-19
Medium Priority
Last Modified: 2010-04-16
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
Question by:sarniscool
Welcome to Experts Exchange

Add your voice to the tech community where 5M+ people just like you are talking about what matters.

  • Help others & share knowledge
  • Earn cash & points
  • Learn & ask questions
LVL 32

Expert Comment

ID: 2732262
I think you might be disappointed.

Anyway, one good place is www.codeguru.com.

Expert Comment

by:Jan Louwerens
ID: 2732322
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  =)
LVL 22

Expert Comment

ID: 2732393
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:
Concerto Cloud for Software Providers & ISVs

Can Concerto Cloud Services help you focus on evolving your application offerings, while delivering the best cloud experience to your customers? From DevOps to revenue models and customer support, the answer is yes!

Learn how Concerto can help you.


Expert Comment

ID: 2733533
"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
LVL 32

Expert Comment

ID: 2735344

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!

Expert Comment

ID: 2736036
Remember, if you can't be replaced, you can't be promoted

Expert Comment

ID: 2738958
DVB, If you can comment code on demand, you can be promoted :)
LVL 24

Accepted Solution

SunBow earned 200 total points
ID: 2739358
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?

Featured Post

Enroll in October's Free Course of the Month

Do you work with and analyze data? Enroll in October's Course of the Month for 7+ hours of SQL training, allowing you to quickly and efficiently store or retrieve data. It's free for Premium Members, Team Accounts, and Qualified Experts!

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

In this post we will learn how to connect and configure Android Device (Smartphone etc.) with Android Studio. After that we will run a simple Hello World Program.
We live in a world of interfaces like the one in the title picture. VBA also allows to use interfaces which offers a lot of possibilities. This article describes how to use interfaces in VBA and how to work around their bugs.
Simple Linear Regression
Introduction to Processes

636 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question