In my opinion, code would be worlds easier to read, learn, debug, and understand if more programmers stopped using [unnecessary] abbreviations and started writing self-documenting code. Self-documenting code is...well, code that doesn't need explanation or comments to explain its function.

Here's an example from http://www.cprogramming.com/snippets/source-code/

.

/* n= positive integer e= power S= sum of integers raised in e power */

int e,n,i,S=0;

.

Is there really a reason for this sort of abbreviation? I see it all the time, everywhere, and even in learning materials. I don't really understand because as far as I know there aren't any technical limitations that would require such abbreviations to be used. On another note, " i " is later used in its usual fashion in a for-loop...but I've never seen it declared outside of the loop before.

So why not write it in a self-documenting fashion:

.

int power, positive_integer, sum_of_integers_raised_to_a_power;

.

If it's about typing long variable names, I don't really understand that notion. We're programmers, right? I'm not a professional or anything, but in the long run I believe it's worth the extra effort because when you're working with other people, no-one will have to spend time learning your coding style or searching for comments to figure out what the source is doing. Besides, most programming software offer code completion.

Sorry for little rant. I promise that I'm not just searching for petty things to talk about here. It just strikes me as a real problem. If you have throw-away variables that don't need to stick around for later use, like the following example, it's not that big a deal.

.

// This is perfectly OK! It's still easy to read!
string phrase = "Hello!";

for(int i = 0; i < phrase.size(); i++){
    cout << phrase.at(i);
}

// This, however, probably needs a comment!
string p = "Hello!";

for(int i = 0; i < p.size(); i++){
    cout << p.at(i);
}

.

How many of you write self-documenting code? If you don't always do so, what are your reasons for not using this style?

The idea you propose - writing fully descriptive names - is only a small part of the picture. I find sum_of_integers_raised_to_a_power particularly pedantic.

I focus mostly on isolating small functions which are descriptive by themselves and suggest by themselves an order of call.

This is not always possible; mostly because of time/effort constraints. Sometimes, it just isn't worth it.

Using single-letter identifiers is universally considered bad but for a two-liners it might be acceptable.

Using single-letter identifiers is universally considered bad but for a two-liners it might be acceptable.

I'm not sure why most programmers seem to be doing this but it is a wide-spread phenoma. Robert C. Martin goes into the subject in 'Clean Code' (which in my opinion should be standarized reading material for EVERY and ALL programmers which they should re-read every one or two years).

I've ran into these issues at my current job more than once and over there it is a cultural thing. Many of my colleagues find that writing three letter variables is less work(because hey, intellisense isn't there to autocomplete it the first time you write it out) and prefer to write everything according to the hungarian misnotation. The result is a mix of incredibly unreadable code, mixed in with prefixes such as int, dbl, bln on variables are all different types(in many cases not even the type declared in the variable name) with sometimes a line of comment above each regular line of code, such as:

// loop over all the items in the list
for (var objItem in lstItems)
{
    // do something with objItem
    DoSomething(objItem);

    // Transfer into the list of processed items
    lstProcessedItems.Add(objItem);
}

What I've seen in my work is that the more people stick to basic guidelines such as the Single Responsiblity Principle(SRP) and the like the more likely they are to also write self-documenting code. The more you mix different aspects together the less easy it becomes to write code that documents itself because boundaries become fuzzy and naming isn't as exact and simple as when an object or a method does only one thing.

I do agree with single letter variables are a big no-no unless you're using Linq(Where(o => o != null) is as readable as Where(theObject => theObject != null)), loop-variables to signify index or loop values.

But in the end: since every book or tutorial seems to abbreviate things it is what you learn first. And first habits are easily becoming engrained as the norm.

I generally write self documenting code as much as I can. A lot of comments on everything just makes the code look cluttered, and I figure that if my code isn't easily readable, then one of two things is going on:

(a) My code sucks and needs to be refactored and rewritten to make more sense.

(b) It's a really complicated problem that can't really be refactored and should probably be explained with comments where necessary.

When working on contract projects my clients have always loved the way that I write clean readable code, because they really don't have time to read through a bloated mess filled with comments that explain a ton of simple get and set functions before they can figure out how to use the module I wrote. The ironic thing is that when I started taking classes to get a degree in computer science the professors knocked off a bunch of points for writing the kind of code that's actually useful in a production environment.

I do not comment my code. As mentioned before, if it needs a comments, it is probably in need of re-factoring.

But, I do document any libraries that will be used for multiple projects. APIs should be documented. But I find that I never look at comments anyway. I find out everything I need from the unit tests or simple example code.

What I find more useful is making code easy to find. For example, I've got a GUI with a bug. So I need to find that code behind the button. Where is it? I have no idea. So I do a search for a string on that panel that looks unique, and I find the panel. All my gui panels have the same public void initialize() methods that sets up the GUI. So I know right where to go. And then I find the button. The button has code like this:

private JButton getButton() {
  if( button == null ) {
     button = new JButton( "button name" );
     button.addActionListener( new ActionListener() {
        public void actionPerformed( ActionEvent e ) {
           controller.onWeirdButtonPressed();
        }
     });
  }
  return button;
}

Ah, there is is. All the code is in controller.onWeirdButtonPressed(); Nothing is passed in, nothing is assumed, and everything that needs to happen when this button is pressed is in this method. Documented code does you no good if you can't find it.

code like "if (n<=0) /* if n is a negative number*/" is just silly.

And incorrect ;) 0 is not a negative number