Solved

PROFESSIONAL SOURCE CODES

Posted on 2000-04-19
8
177 Views
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
0
Comment
Question by:sarniscool
8 Comments
 
LVL 32

Expert Comment

by:jhance
Comment Utility
I think you might be disappointed.

Anyway, one good place is www.codeguru.com.
0
 
LVL 5

Expert Comment

by:Jan Louwerens
Comment Utility
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  =)
0
 
LVL 22

Expert Comment

by:cookre
Comment Utility
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:
http://www.sysinternals.com
0
 
LVL 3

Expert Comment

by:y2kwacko
Comment Utility
"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
0
Better Security Awareness With Threat Intelligence

See how one of the leading financial services organizations uses Recorded Future as part of a holistic threat intelligence program to promote security awareness and proactively and efficiently identify threats.

 
LVL 32

Expert Comment

by:jhance
Comment Utility
y2kwacko,

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!
0
 
LVL 3

Expert Comment

by:DVB
Comment Utility
Remember, if you can't be replaced, you can't be promoted
0
 
LVL 3

Expert Comment

by:y2kwacko
Comment Utility
DVB, If you can comment code on demand, you can be promoted :)
0
 
LVL 24

Accepted Solution

by:
SunBow earned 50 total points
Comment Utility
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?
0

Featured Post

Free Trending Threat Insights Every Day

Enhance your security with threat intelligence from the web. Get trending threat insights on hackers, exploits, and suspicious IP addresses delivered to your inbox with our free Cyber Daily.

Join & Write a Comment

Displaying an arrayList in a listView using the default adapter is rarely the best solution. To get full control of your display data, and to be able to refresh it after editing, requires the use of a custom adapter.
Since upgrading to Office 2013 or higher installing the Smart Indenter addin will fail. This article will explain how to install it so it will work regardless of the Office version installed.
In this fifth video of the Xpdf series, we discuss and demonstrate the PDFdetach utility, which is able to list and, more importantly, extract attachments that are embedded in PDF files. It does this via a command line interface, making it suitable …
In this seventh video of the Xpdf series, we discuss and demonstrate the PDFfonts utility, which lists all the fonts used in a PDF file. It does this via a command line interface, making it suitable for use in programs, scripts, batch files — any pl…

763 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

Need Help in Real-Time?

Connect with top rated Experts

9 Experts available now in Live!

Get 1:1 Help Now