Gee I hope someone dumps some flame-war fuel on this thread...

I (and Scott Meyer) would suggest avoiding typedefs all together, unless you have to support C++98.

There it is...

Heh, I had no idea that was flame-war fuel, and also no idea vs2012 didn't support it.

This is probably worse flame-war fuel:

I think type aliases for complex types are awesome, regardless if you use typedef or using, but it can get pretty annoying when you type alias basic built in types and simple containers all over the place.

A bit of flame dousing:

It's not an easy line to draw though...

I promise to not post anything more about type aliases after this post ;)

There are some people out there that think Mr. Myers and all the new C++ stuff is useless, and they just use plain C.

But I wasn't really serious there. *or was I?*

I usually write rather self-documenting code.. but I have sometimes noticed that it becomes so very much text that it actually makes it harder to read when I get back to it a while later. If there's a lot of code that doesn't have clear syntax-coloring I also add comments just to add some different-colored separators that makes stuff easier to find quickly.

Especially with VS preview-scrolling I started to get a tendency to find my way in the code by patterns in the scroll-bar :) I recently disabled that again though because I felt it took too much space when trying to fit two source-tabs on the same monitor so now I'm back to having to write my code more easily navigable.

I always strive to make code easy to read and understand. Abbreviations are almost never used, except where universally understood (not internal jargon). Comments mostly try to give context, e.g. code might be funkier than hoped due to past bug fixes for non-obvious situations, or to illustrate the reason why a certain implementation decisions were made.

As to whether the result is actually "self documenting", that is for the reader to determine.

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

And incorrect ;) 0 is not a negative number

But this is the kind of thing that happens when comments attempt to "document" the code in too much detail, they tend to get out of sync - perhaps that used to be a test for negative numbers but was changed due to refactoring, a bug or a feature request...

So why not write it in a self-documenting fashion:
.
int power, positive_integer, sum_of_integers_raised_to_a_power;
.

I would say that these are poor examples of good names too. 'power' is somewhat OK, but 'power' of what? it requires additional context to know.

'positive_integer' and 'sum_of_integers_raised_to_a_power' are bad for another reason: they repeat what they are (the code already does this), and give no clue what they are *for*.

Self-documenting code is great, but not if we repeat the mistakes of poor (over)commenting by simply recasting it as the names of our variables. Self-documenting code is more about writing code that is easy to read and intuit about -- this means, primarily, that units of code (functions, variables, modules, etc) are ideally able to be readable in a stand-alone fashion, and that code boundaries (names, parameters, return values, etc) are well-named, unambiguous, and document their requirements, preconditions, and post-conditions. Do these things pervasively, and you should require very few comments in straight-line code that relates to its function (You'll still want to comment where it provides relevant context to *why* you've done something a certain way, just very few comments relating to *how* you've done something).

I think type aliases for complex types are awesome, regardless if you use typedef or using, but it can get pretty annoying when you type alias basic built in types and simple containers all over the place.

Whenever im working on something that has to support multiple platforms, I end up aliasing most of the basic built in types.

As with anything its something that can be abused, and does get annoying when it doesnt have any semantical impact.

ex. stuff like this is good

typedef signed char		i8;
typedef unsigned char		u8;

stuff like this is stupid:

typedef signed char        schar;
typedef unsigned char      uchar;

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.

It's probably worth pointing out that your examples reuse well known mathematical symbol patterns. e for exponent, or possibly derived from the mathematical constant that is the base of the natural logarithm; n from the set of Natural Numbers; i from index; and S from summation, often represented in mathematical formula by the symbol sigma (?, also the Greek alphabet equivalent of 'S'). What you are running into here is the tension inherent in jargon, in that it increases communicative density for the expert, but it baffles the uninitiated.

Also, older programming languages often encouraged the use of shorter variable names because of line length limits. When you only have 80 characters to a line (8 of them reserved for line numbers and continuation markers), sum_of_integers_raised_to_a_power is not going to fly.

All that said, you are correct that we should all strive to be more transparently communicative in our code/nomenclature, without requiring comments. One very good reason to avoid needing comments to explain code is that the comments also need to be maintained as the code changes! In general, I reserve comments for context—information about the code that can not be gleaned from reading it, either due to an environmental constraint or an algorithmic/mathematical prerequisite.

So why not write it in a self-documenting fashion:
.
int power, positive_integer, sum_of_integers_raised_to_a_power;
.

I would say that these are poor examples of good names too. 'power' is somewhat OK, but 'power' of what? it requires additional context to know.

'positive_integer' and 'sum_of_integers_raised_to_a_power' are bad for another reason: they repeat what they are (the code already does this), and give no clue what they are *for*.

Self-documenting code is great, but not if we repeat the mistakes of poor (over)commenting by simply recasting it as the names of our variables. Self-documenting code is more about writing code that is easy to read and intuit about -- this means, primarily, that units of code (functions, variables, modules, etc) are ideally able to be readable in a stand-alone fashion, and that code boundaries (names, parameters, return values, etc) are well-named, unambiguous, and document their requirements, preconditions, and post-conditions. Do these things pervasively, and you should require very few comments in straight-line code that relates to its function (You'll still want to comment where it provides relevant context to *why* you've done something a certain way, just very few comments relating to *how* you've done something).

Everything Ravyne said, too.

Ok guys. I would like to say that you should take "sum_of_integers_raised_to_a_power" as a mildly facetious replacement for "n". I was trying to say, "If you're going to use a letter to represent a variable that isn't an iterator, and take the time to comment in order to explain its function, why not just name the variable what you were going to say in the comment? At least you don't have to scroll up the screen to see what "n" is supposed to represent later on, scratch your head when you look at it next week, and then repeat the whole process."

Self-documenting can mean many things to many people. To me, it just means plain English (not unlike our current discussion). For the computer, it doesn't really care what we do because it all boils down to machine code. But for our purposes, we have to be able to edit, debug, and read the source. When I was first learning, everyone else used abbreviations so I used abbreviations too because I thought it was the only way to write code. At some point though, I realized: "Waaaaiiiiit a minute, I can't read any of this!" Later, I realized that it wasn't the only way to write code. Thus, my face changed from to .