Single-line Javadoc comments? 2

[cpjust]

I was wondering if there's such a thing as a single line Javadoc comment, similar to this which works in Doxygen?

class Shape
{
   int m_Length;  /**< The length of the shape. */
   int m_Width;   /**< The width of the shape. */
...

which would use the comment to the right of the variable in the Javadoc rather than having to do this:

class Shape
{
   /** The length of the shape. */
   int m_Length;

   /** The width of the shape. */
   int m_Width;
...

which takes up more vertical space.

 

[stefanwagner]

You could do it this way:

/**< The length of the shape. */   int m_Length;  
/**< The width of the shape. */    int m_Width;

but you should get rid of the prefix m_ - that is pre-cobol-style.

so length and width in class Shape are length of the shape and width of it.


don't visit my homepage:

http://home.arcor.de/hirnstrom/minis/index.html

 

[cpjust]

Yeah, I didn't think there was a way to do it (on the right side) with javadoc. :-(

BTW, I would definitely disagree about not prefixing member variables (if not with m_ then at least with something) because then it immediately stands out in code as a member variable without having to look through the function to see if the variable was declared in the function or in the class. It also prevents variable hiding when someone uses the same name as the member variable (unless they do something dumb and use m_name as the local variable or function parameter).
I've seen some people differentiate member variables by prefixing it with this. but that's 3 extra characters to type and easy to forget in some places.

 

[tom62]

My 2cts, I've used something similar like "m_" when I was a Java newbie. Later I realized that it was more important to name your variables properly and to use them at the right place than prefixing them with a kind of identifier. In my opinion we should not write unnecessary code (the superfluous use of this. is a bad example of it) and focus more on good program design. If someone cannot distinguish between a class or local variable in his own program and needs a prefix to keep them apart than he is not a good programmer.

 

[cpjust]

With very short functions, it's easy to see which variables are local, but with long functions you need to scroll through the whole function and look for where the variable declarations are to see if a variable is declared locally or not.
I'm certainly not advocating Hungarian notation where you put s for strings, b for booleans, i for ints... But m_ for member variables is not the same as Hungarian notation in my opinion.
I agree that variables should have useful names, but how would you name a variable in a way that makes it clear that it is a member variable rather than a local variable without using something like a m_ prefix?

 

[tom62]

Prefixing variable names comes, like Stefan already said, from the "good" old Cobol times. You won't find it in the Sun's Java Coding Standards. In Cobol you don't have local variables, hence the need to identify them "ad nauseam" . Many people stuck to that Cobol standard when they moved to Java.

The prefixing of variable names is not a crime, nor is it wrong . Feel free to use anything that you feel comfortable with and what makes your life easier. Whenever I work on a project, I use the coding standards that are agreed upon for that project. If that includes prefixing variable names then I stick to that rule. However, with a modern IDE, like Eclipse, it is very easy to find out whether your variables in your functions are local or nor. This makes this prefixing of variable names rather unnecessary for me.

I think it is all a matter of design. If I see dozens of member variables declared as protected, public or static in a class, without any getter- or setter methods then alarm bells start to ring, even if those variables have a prefix in their name or not. Coding standards are OK and necessary, but it doesn't prevent people to write bad code.

 

[stefanwagner]

Yes, I would not name a variable in a way that makes it clear that it is a member.

Short methods don't need it at all, and short methods is the way to go.

Well - there are exceptions, where methods are longer than 10 lines, and use more than 3 local variables - then you may use an IDE which highlights members or displays tooltips in the rare case you need it.

In the list of attributes it's annoying to have all of them prefixed, which makes it harder to read the name, which should reflect the meaning. And an alphabetically sorting tool will put them all together.

Did you ever communicate over the phone about a class? "M underline name equals opening brace p underline name ...".


don't visit my homepage:

http://home.arcor.de/hirnstrom/minis/index.html

 

[Diancecht]

m_ is the beginning, the you start using __NAMES for static variables ...

Cheers,
Dian

 

[cpjust]

However, with a modern IDE, like Eclipse, it is very easy to find out whether your variables in your functions are local or nor. This makes this prefixing of variable names rather unnecessary for me.

True, but what about code reviews where you look at a print out of the code, or a diff of the code in a code review program? Then it's not so easy to tell which are member variables.
Anyways, I'll continue using m_ for member variables.

Now if I can only convince the others in my group to drop the Hungarian Notation... ;-)

 

[TonHu]

Now if I can only convince the others in my group to drop the Hungarian Notation...;-)

m_ is just another dialect of Hungarian. As said before, it's called Cobolian :-D, others may call it Archaian.

 

[tom62]

This discussion reminds me of Roedy Green's excellent essay "How to write unmaintainable code" (

http://mindprod.com/jgloss/unmain.html),

which is enormous fun to read.

Some quotes about naming

Reuse of Global Names as Private
Declare a global array in module A, and a private one of the same name in the header file for module B, so that it appears that it’s the global array you are using in module B, but it isn’t. Make no reference in the comments to this duplication.

Recycling Revisited
Use scoping as confusingly as possible by recycling variable names in contradictory ways. For example, suppose you have global variables A and B, and functions foo and bar. If you know that variable A will be regularly passed to foo and B to bar, make sure to define the functions as function foo(B) and function bar(A) so that inside the functions A will always be referred to as B and vice versa. With more functions and globals, you can create vast confusing webs of mutually contradictory uses of the same names.

Recycle Your Variables
Wherever scope rules permit, reuse existing unrelated variable names. Similarly, use the same temporary variable for two unrelated purposes (purporting to save stack slots). For a fiendish variant, morph the variable, for example, assign a value to a variable at the top of a very long method, and then somewhere in the middle, change the meaning of the variable in a subtle way, such as converting it from a 0-based coordinate to a 1-based coordinate. Be certain not to document this change in meaning.

Misleading names
Make sure that every method does a little bit more (or less) than its name suggests. As a simple example, a method named isValid(x) should as a side effect convert x to binary and store the result in a database.

m_
a naming convention from the world of C++ is the use of "m_" in front of members. This is supposed to help you tell them apart from methods, so long as you forget that "method" also starts with the letter "m".

o_apple obj_apple
Use an "o" or "obj" prefix for each instance of the class to show that you’re thinking of the big, polymorphic picture.

Hungarian Notation
Hungarian Notation is the tactical nuclear weapon of source code obfuscation techniques; use it! Due to the sheer volume of source code contaminated by this idiom nothing can kill a maintenance engineer faster than a well planned Hungarian Notation attack. The following tips will help you corrupt the original intent of Hungarian Notation:

* Insist on using "c" for const in C++ and other languages that directly enforce the const-ness of a variable.
* Seek out and use Hungarian warts that have meaning in languages other than your current language. For example insist on the PowerBuilder "l_" and "a_ " {local and argument} scoping prefixes and always use the VB-esque style of having a Hungarian wart for every control type when coding to C++. Try to stay ignorant of the fact that megs of plainly visible MFC source code does not use Hungarian warts for control types.
* Always violate the Hungarian principle that the most commonly used variables should carry the least extra information around with them. Achieve this end through the techniques outlined above and by insisting that each class type have a custom wart prefix. Never allow anyone to remind you that no wart tells you that something is a class. The importance of this rule cannot be overstated: if you fail to adhere to its principles the source code may become flooded with shorter variable names that have a higher vowel/consonant ratio. In the worst case scenario this can lead to a full collapse of obfuscation and the spontaneous reappearance of English Notation in code!
* Flagrantly violate the Hungarian-esque concept that function parameters and other high visibility symbols must be given meaningful names, but that Hungarian type warts all by themselves make excellent temporary variable names.
* Insist on carrying outright orthogonal information in your Hungarian warts. Consider this real world example: "a_crszkvc30LastNameCol". It took a team of maintenance engineers nearly 3 days to figure out that this whopper variable name described a const, reference, function argument that was holding information from a database column of type Varchar[30] named "LastName" which was part of the table’s primary key. When properly combined with the principle that "all variables should be public" this technique has the power to render thousands of lines of source code obsolete instantly!
* Use to your advantage the principle that the human brain can only hold 7 pieces of information concurrently. For example code written to the above standard has the following properties:
o a single assignment statement carries 14 pieces of type and name information.
o a single function call that passes three parameters and assigns a result carries 29 pieces of type and name information.
o Seek to improve this excellent, but far too concise, standard. Impress management and coworkers by recommending a 5 letter day of the week prefix to help isolate code written on 'Monam' and 'FriPM'.
o It is easy to overwhelm the short term memory with even a moderately complex nesting structure, especially when the maintenance programmer can’t see the start and end of each block on screen simultaneously.

Hungarian Notation Revisited
One followon trick in the Hungarian notation is "change the type of a variable but leave the variable name unchanged". This is almost invariably done in windows apps with the migration from Win16 :- WndProc(HWND hW, WORD wMsg, WORD wParam, LONG lParam) to Win32 WndProc(HWND hW, UINT wMsg, WPARAM wParam, LPARAM lParam) where the w values hint that they are words, but they really refer to longs. The real value of this approach comes clear with the Win64 migration, when the parameters will be 64 bits wide, but the old "w" and "l" prefixes will remain forever.

 

[Diancecht]

Great article!

I will open a request to the Java specification so m_ and other underscores in variables or methods name throw compilation errors.

Cheers,
Dian

 

[cpjust]

m_ is just another dialect of Hungarian. As said before, it's called Cobolian :-D, others may call it Archaian.

Hungarian Notation uses prefixes to denote the type of the variable. m_ denotes the scope of the variable.

Even in the quotes tom62 posted, m_ and Hungarian Notation are separate quotes.

m_
a naming convention from the world of C++ is the use of "m_" in front of members. This is supposed to help you tell them apart from methods, so long as you forget that "method" also starts with the letter "m"

I don't understand the last part of that quote. Are they saying some people actually name all their member functions with an 'm' prefix? If so, well, that's just stupid. Other than that, I can't see any negative comment about m_ in that quote.

 

[andyberlin2000]

Dear Stefan, dear Tom62 !
Young people like you (born nearly in the middle of last century) should not talk in such a respectless way about the good old days - when programmers could save 20-40 Bytes reprogramming their assembler code during runtime and doing other sophisticated things.

As one of the last living programmers who actually wrote COBOL code I MUST INSIST on the fact that neither myself nor any of my collegues (who may watch from above...) EVER USED SUCH m_whatever shit THAT DEFINITELY LOOKS LIKE MICROSOFT STUFF (C++ MFC) - but all rules and standards come from these lucky people WHO DON'T HAVE TO write working code because they are professors at some university. Since I already started programming when electrons still were made of wood I have really seen all fashions come and stay. THE USER STILL GETS THE SAME SHIT PROGRAMS because programmers don't fight for usability, comfort and completeness in the work flow. They only fight for everything else (preferrably "Frameworks"...)

You can fight with Stefan for hours about how many blanks should be used for indentation - you would see me rather fighting whether to have SUSHI or a good THAI CURRY.
Maybe you should concentrate on that for a change....

 

[tom62]

Great post, andyberlin2000. I just wonder how you identified member variables in your assembler code . I started out as a COBOL programmer, so I know what it is to write programs that runs without problems for several decades, but always look bad on a computer screen. Oh, those good old days, when a debugging session meant that you had to analyze a memory dump on mountains of paper; when frameworks didn't exist; ASCII and EBCDIC where the only standards (bad luck, if you didn't live in an English speaking country); and every for loop took twenty minutes to code and five hours to compile on punch cards .

BTW I love your idea to start a fight here about proper code indentation, sushi and Thai curry !

 

[Diancecht]

As one of the last living programmers who actually wrote COBOL code

I'm rigth now surrounded by COBOL (and PL-I) programmers, as anyone working on a bank would be, so don't worry: your legacy will survive.

And I agree COBOL conventios are way much better than C/C++ __m_STUFF___ but I still see "cobolian" ways of non-vocals naming like MSTRCRFG and so on

Cheers,
Dian