No comments in code i was asked to fix - none whatsoever

Question

1.00/5 (1 vote)

See more:

I've just recently finished just over a year's worth of fixing some seriously broken code (DB/Front end stuff) and it was completely devoid of comments.

To make things even trickier, whoever wrote it was a big fan of cryptic variable names which in no way described their purpose or function. What does a variable called (say) 'ip' mean? in this particular case it referred to an internal counter used for tracking how many items belonged to a pallet of goods. Not exactly intuitive.

My question is, is this normal? Were they just lazy? Or were they trying to hide something?

In my own code, I document everything from what I'm trying to achieve, what's tripped me up, how I'm feeling - basically down to the socks and undies I'm wearing on that particular day.

My tutor drummed into my head that: It's suprising what you can forget in a month, let alone a year, so document, document everything.

So anyway, I just wondered if this was the norm. Thanks for reading my mini rant. Now that I've fixed everything I'm back applying for the dole.

What I have tried:

Descriptive variable names, adding explanatory summarys to methods, doing my very best to create self-descriptive code

Posted 27-Feb-16 12:33pm

BruceN

Updated 27-Feb-16 13:49pm

Add a Solution

1 solution

Add a Solution

Add your solution here

Treat my content as plain text, not as HTML

Preview 0

…

Existing Members

Sign in to your account

...or Join us

Download, Vote, Comment, Publish.

Your Email
Password
Forgot your password?

Your Email
This email is in use. Do you need your password?
Optional Password

I have read and agree to the Terms of Service and Privacy Policy
Please subscribe me to the CodeProject newsletters

When answering a question please:

Read the question carefully.
Understand that English isn't everyone's first language so be lenient of bad spelling and grammar.
If a question is poorly phrased then either ask for clarification, ignore it, or edit the question and fix the problem. Insults are not welcome.
Don't tell someone to read the manual. Chances are they have and don't get it. Provide an answer or move on to the next question.

Let's work to help developers, not make them feel stupid.

This content, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

debashishPaul · Answer 1 · 2016-02-27T13:49:00

Human mind works in a mysterious way. The developer might be lazy or might just think whatever they named the variables are descriptive enough in the respective context. That is why it needs a second pair of eyes either through code review or pair programming. The problem you have, I wouldn't say it is normal and it can never be the standard, but I have seen it happening quite frequently.

Documentation is necessary for describing the code you have written. Now, how you should do it depends on the target audiences, most likely to be other developers. The documentation should describe 3 things.

1. You need to tell what is the method.
2. You need to tell why this method is written.
3. You need to tell how the goal has been achieved.

Now, these can be achieved in many ways. What I follow is name my method descriptive enough so that "what" is described. Add a comment on top of each method, which says why the method is needed. Name my variables reasonable enough so that "how" the goal is achieved becomes evident.