Click here to Skip to main content
14,244,102 members
Rate this:
Please Sign up or sign in to 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
Updated 27-Feb-16 13:49pm

1 solution

Rate this:
Please Sign up or sign in to vote.

Solution 1

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.
   

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

  Print Answers RSS
Top Experts
Last 24hrsThis month



CodeProject, 503-250 Ferrand Drive Toronto Ontario, M3C 3G8 Canada +1 416-849-8900 x 100