This week's giveaway is in the Android forum.
We're giving away four copies of Android Security Essentials Live Lessons and have Godfrey Nolan on-line!
See this thread for details.
The moose likes Beginning Java and the fly likes Documentation & Coding Styles Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "Documentation & Coding Styles" Watch "Documentation & Coding Styles" New topic
Author

Documentation & Coding Styles

Sri Gnana
Ranch Hand

Joined: Apr 29, 2004
Posts: 166
Hi,
Can anyone tell me, where can i get the Documentation & coding style(coding with comments) reference , please give me the URL, if you have an idea please tell me,
Regards
Sri Gnana


Thanks & Regards
Sri Gnana
Everythings Programmed!...
Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 60798
    
  65

Moving to the Java in General(beginner) forum.


[Asking smart questions] [Bear's FrontMan] [About Bear] [Books by Bear]
Dirk Schreckmann
Sheriff

Joined: Dec 10, 2001
Posts: 7023
Different coding conventions are used by many different organizations.
You might like to take a look at the JavaRanch Java Programming Style Guide, and Sun's Code Conventions for the Java Programming Language.


[How To Ask Good Questions] [JavaRanch FAQ Wiki] [JavaRanch Radio]
Stefan Wagner
Ranch Hand

Joined: Jun 02, 2003
Posts: 1923

Avoid the JavaRanch advices.
Some of them are wrong or direct in the wrong direction.
For example:
Use tabs not blanks.
Mixing tabs with blanks or using blanks is a beginners fault.
Allways use tabs and save them as tabs.
You may display them as 6 or 4 blanks, and when someone else opens you file, he sees his settings.
If you used spaces, he will see your spaces.
And a tab is of course 8 spaces.
If you use less than 8, you will sooner or later end up with code like this:

A tab is 8 spaces.
Basta.
See this link for more information:
Indentation
Do not use do..while loops.

I never read like this before!
Of course you need to orient on experienced programmers to improve yourself.
There are more 'never use...' advices which need some critiques. Most of them would be fine, when they were expressed as 'seldom use...' or 'carefully use...' or 'rethink usage of ...' .


http://home.arcor.de/hirnstrom/bewerbung
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
Mixing tabs with blanks or using blanks is a beginners fault.
Stefan, I too disagree with the JavaRanch style guilde on many issues, but let's not misrepresent it. The guide does not in any way condone mixing tabs and spaces. Rather, it requires spaces, period.
Sun, on the other hand, advocates mixing them. I consider this the worst thing about Sun style (which I generally prefer to Ranch style) - mixing tabs and spaces is always wrong. All spaces is OK; all tabs is OK; mixing them is not.
Note that if you indent with tabs when posting code to the ranch, most browsers will render this at 8 spaces. Code written like this can easily become too wide to display properly on most people's browsers, and few people know how to readjust the tabs on their web browser. So for posting to JavaRanch, tabs are usually a bad idea.
[B]If you use less than 8, you will sooner or later end up with code like this:
[/B]
Completely untrue. I and most programmers I've know use 4 spaces per indent, and I'd never write such hideous-looking code. I used to use two spaces per indent, and there was still no need. If you ever see someone writing code like this, the problem is usually that their methods are too long, and need to be broken up. I shudder to think how long a method might have to be before 8-space indents are necessary.
There are more 'never use...' advices which need some critiques. Most of them would be fine, when they were expressed as 'seldom use...' or 'carefully use...' or 'rethink usage of ...' .
I completely agree with this.
[ April 30, 2004: Message edited by: Jim Yingst ]

"I'm not back." - Bill Harding, Twister
Dirk Schreckmann
Sheriff

Joined: Dec 10, 2001
Posts: 7023
Avoid the JavaRanch advices.
Some of them are wrong or direct in the wrong direction.

Hmm... How can it be wrong?
If you don't like it, to me that seems like a different beast than it being wrong.
Personally, I prefer that those I work with follow any consistent style in formatting their code. It helps a lot when trying to understand their code. I'm less concerned that they are wrong or right in their choice of style (as if I believed in such a concept).
Warren Dew
blacksmith
Ranch Hand

Joined: Mar 04, 2004
Posts: 1332
    
    2
Originally posted by Jim Yingst:
Sun, on the other hand, advocates mixing them. I consider this the worst thing about Sun style (which I generally prefer to Ranch style) - mixing tabs and spaces is always wrong. All spaces is OK; all tabs is OK; mixing them is not.

If I recall correctly, Sun's style guide not only advocates mixing them, but advocates indents and tabs of different amounts (4 space indents and 8 space tabs). I think it would maintain incredible code discipline to maintain this.
In my experience, an "all tabs" rule is very difficult to enforce - at some point, someone will delete something to the left of some spaces and end up using the spaces as an indent, perhaps not realizing it's not a tab. I think to make tabs work, you have to enforce a tab setting.
I personally prefer all spaces - possibly my only point of agreement with the Java Ranch suggestions. Spaces work the same for everyone except perhaps the very rare programmers who use proportional fonts.
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
I got management to buy everyone on our team this book http://www.ambysoft.com/elementsJavaStyle.html for about $10.00. We have evolved a short set of additions and exceptions. I recently added a team standard configuration for the Eclipse source code formatter to help get more consistent indentation and such. I use Ctrl-Shift-F nearly every time I save and run a unit test.
As a counter to common JavaDoc specs, there's a school of thought that any method that needs a comment has something wrong with it, and you can code so clearly that no comments are necessary. I buy that for situations where the reader will have the code, but like to see package and class docs that give readers without the code a good idea how to use the classes.


A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
clio katz
Ranch Hand

Joined: Apr 30, 2004
Posts: 101
since it's clear there is no *single* coding/documentation standard ... my suggestion would be to
1. choose your own 'best practices' from those presented,
2. enforce practices with your editor settings eg. jEdit (jedit.org), and
3. periodically check how you're doing with a tool like checkStyle (http://checkstyle.sourceforge.net/) etc.
Note: checkStyle is nice because you can customize the 'standards' to those you prefer... (and, well, it's free:-)
i'll steer clear of the tabs/indentation issue ... i still can't believe that the short 80-char java lines are due to some outdated notion about screen widths (i thought i was the only one old enough to remember 'cardimage' ... anyone?)
sever oon
Ranch Hand

Joined: Feb 08, 2004
Posts: 268
Why is this even a topic of discussion in the 21st century? Where are all the revision control systems that automatically recognize the language and strip out all unnecessary whitespace, only to be added back in by the developer's own IDE, configured to that person's preference? Why, in this day and age, do I have to code the way someone else wants me to code for ANY reason?
sev
Mike Gershman
Ranch Hand

Joined: Mar 13, 2004
Posts: 1272
Reposting my comments from another forum:
Typographic consistency is important in smoothly assimilating printed text. In the case of Java, I see a number of people promoting subtly different standards. For example, Kathy Sierra suggests that do ... while loops are always bad style. One of my professors threatened to reject any homework using the conditional operator. And the argument over whether { belongs on the same line as "if ( )" or on the following line seems endless. While these variations each have reasons, they eat into the benefits of standardization.
One stated defense of these variations is that working programmers must be prepared to adopt the style in use at their particular shops. However, people change jobs, they use code from other shops, and they read manuals.
I have not seen a convincing reason why everyone doesn't just get solidly behind the Sun standard until it is in universal use.

I might add that IMHO putting spaces on both sides of almost every identifier, as recommended by JavaRanch style guide is as strange looking as the reason given. If there is still an editor so primitive that it is confused by punctuation marks adjacent to identifiers, it's not worth using.


Mike Gershman
SCJP 1.4, SCWCD in process
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
Personally reformatting every file you edit to your favorite format is fine for you, but will confuse the heck out of most text comparison tools that someone might use to merge or track or find changes. Teams benefit from standards. Leave your formatting ego at the door - I really don't want to be able to tell who wrote what from formatting.
Stefan Wagner
Ranch Hand

Joined: Jun 02, 2003
Posts: 1923

we didn't start the fire ...
stan: since editors have their own idea, of how to show indentation, and how to save, you might not mention a reformatting.
Ok - you could save tabs as tabs and spaces as spaces, but if the sourcecode you get is already mixed, you have a mess in your editor.
Then I would prefer the solution of...
sever oon: well - that's how I do. I use my indentation tool and other people shall use theirs. There is the problem of very subtile differences I make in some cases, leading to very complex rules of indentation, but for instance eclipse 3.0.0 M8 is going in a good direction. And I will not change my style in every new company!
warren: if you have 8 spaces tabs, nobody will think - after deleting something to the left, the remaining space might be a tab .
dirk: giving advice to novices, the author may simplify things. But if he gives advices in that absolute manner, simplifying that much is missleading. (never use two returns in a method, never use 'do... while').
It's ********. It's a wrong advice.
You may replace every do_while with a while..., but you needn't. It's wrong.
Wrong wrong wrong.

An early return can simplify your method, making it easier to understand today. Syntaxhighlightening is your friend. Fly with the eagle or scratch with the chicken - ok - I know, this is a chicken-friendly place so I try to get nice again .
Tok tok tok...
That's simply a little bit wrong.
Jim: I posted a lot of sourcecode to the forum, allways using tabs. I didn't see a problem with the layout, but of course I don't know which browser the people use, and how they setted them up.
But I cannot code with regards to snipplets, pasting into a forum, where some unknown algorithm is making html of it, showing it in x browsers on y OS with Z settings in mind!
And the entire article doesn't focus on coding-style in context of the JavaRanch forum.
Testing indentation in a browser...

It is right formatted in mine: 8 spaces, but a lot of place to nest more and more. Anybody having problems?
Most source-code found in the forums is much too long, not too wide
But that's an different issue.
-- edited after testing how it looks in my browser and for layout enhencement--
[ May 04, 2004: Message edited by: Stefan Wagner ]
[ May 06, 2004: Message edited by: Paul Wheaton ]
Sri Gnana
Ranch Hand

Joined: Apr 29, 2004
Posts: 166
Hi,
Thank you !
paul wheaton
Trailboss

Joined: Dec 14, 1998
Posts: 20495
    ∞

Hundreds (thousands?) of teams use the JavaRanch style guide as their style guide.
With the absolutes that you, Stefan, insist upon, it would seem that you think all of these people, including myself, are pretty dense? Ignorant?
Frankly, I feel it is an honor to be not like you. So I thank you for your indirect compliment.
And on a seperate note, would you be so kind as to edit your message so that it does not contain profanity? Surely a man of such depth, character and rich vocabulary as yourself does not need vulgarity to express himself.
If you would really like to see the JavaRanch style guide "improved", please direct your persuasion on that matter to the JavaRanch forum. This forum is more for helping folks learn the basics of Java.


permaculture Wood Burning Stoves 2.0 - 4-DVD set
Stefan Wagner
Ranch Hand

Joined: Jun 02, 2003
Posts: 1923

Well - I edited my message before, but in the edit-field some paragraphs disappeared.
I'm not sure what's the reason for this - maybee metacharacters in UBB? I didn't find a hint in the 'What is UBB Code?' - section.
I realized the disappearing and opened the forum-view in a new navigator-tab, copied my text to an editor, and restored it in the 'edit post'-field with cut and paste. But of course all the ubb-tags where gone.
I encountered this phenomen before, when editing a posting for the second time, and trying to remove one of the 'message edited by'-lines.
I see that I used a swear-word, to characterize an advice as poor. But I didn't get personal to anyone.
Well, perhaps to the anonymous author.
You aren't the author - are you?
I beg you pardon!
I don't like a language full of swear words myself, but I allways found that using them seldom can make a text more spicy and expressive.
I would never call someone pretty dense for using a too restricted Coding Style to my opinion. I've seen a lot of styles which are less ergonomical in my opinion, and people have different tools, traditions and favors.
And there are a lot of rarely found advices, which please me, i.e.: putting spaces in assignments a = 42; and putting the opening rambled brace in the same column, as the closing.
coming to an end: how shall I deal with the previous post? There is a lot of formatting, which I have to restore, when replacing the odd term with 'It's too restricted'.
May my asking for excuse be enough?
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
Sorry Stefan, you have run afoul of a bug in UBB.
tags and [code] tags don't play well together - not when you edit the post later. Stuff between the
and [code] gets mangled. Sorry, but we're still working on a home-grown replacement for this code. The simplest solution for now, which I usually use, is never to use
at all, only [code]. (Exceptiuon - if you use only [uqote] and not [code] in a post, that also works.) You should be OK now when you re-edit, as long as you don't reintroduce any
tags.
[ May 06, 2004: Message edited by: Jim Yingst ]
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
[PW]: Hundreds (thousands?) of teams use the JavaRanch style guide as their style guide.
Some under mild protest, of course.
Why just today I was at a presentation where I saw code adhering to Ranch standard which didn't display well on the screen because 120 chars per line is just not practical on some systems. Code which requires people to use their horizontal scroll bar is evil. However I resisted the temptation to point this out during the presentation, since the presenter is a good friend of mine. (Though sometimes misguided.)
Nick George
Ranch Hand

Joined: Apr 04, 2004
Posts: 815
I'm going to use this opportunity to demonstrate my dilitantism, what's so bad about that code? I suppose I prefer larger indents, but is that the only issue? what do the comments demonstrate?

Originally posted by Stefan Wagner:



I've heard it takes forever to grow a woman from the ground
Stefan Wagner
Ranch Hand

Joined: Jun 02, 2003
Posts: 1923

If you use deep indentation, you easily see the corresponding opening brace, and don't need a comment, to make clear, which block is getting closed.
If you use the popular 3-spaces or 2-spaces indentation, you will often not see with a single look, which block is ending here, and therefore people found a workaround for 'correct indentation': the closing-braces-comment.
In my opinion it looks ugly.
Mike Gershman
Ranch Hand

Joined: Mar 13, 2004
Posts: 1272
Are there really hundreds (thousands?) of teams that would write the following:
BTW, are the editors that are confused by designed for Java code or generic editors?
paul wheaton
Trailboss

Joined: Dec 14, 1998
Posts: 20495
    ∞

I hope they are using "int[] intarray = { 10 , 5 , 7 , -3 };"
sever oon
Ranch Hand

Joined: Feb 08, 2004
Posts: 268
I think the few people that responded to my post didn't get me. One person said that letting each person work in their own format would confuse text comparison tools. You, good sir, didn't read me.
I'm saying that ALL unnecessary whitespace should be removed from code before it's checked into any revision control system. That should be part of the revision control system itself. The code that lives in the DB would indeed be totally unreadable.
However, when person X comes along and opens a source file in thier IDE, it would be automatically formatted to whatever their preferences happen to be, no matter how weird or bizarre, it doesn't matter cuz they're the only ones that will ever see it that way. Person Y looks at the same file in their IDE, configured for their formatting preferences, they see it their way...get it? When they're done making edits and they're ready to commit, the revision control system once again sucks out all whitespace that is not absolutely necessary.
Let's say X does a "compare to latest version" on a modified source file. The IDE would intelligently pull the latest version from CVS, format it according to their preference, and THEN apply the compare tool.
This is so simple. Why hasn't someone done this already? Why do I continue having to live with other people's formatting styles as if we're using quills?
sev
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
[Paul]: I hope they are using "int[] intarray = { 10 , 5 , 7 , -3 };"
I was thinking intArray would be better, actually. And of course

is completely OK according to the Coop guide. (Strange as it may seem.) But I'd still prefer


Working backward through assorted comments...
[Mike]: BTW, are the editors [...] designed for Java code or generic editors?
I suspect they're designed for Cobol or Fortran; I've never used one.
[Joseph]: what's so bad about that code?
Well "} // end if" isn't the end of the world I suppose. But I personally find it ugly and unnecessary, more work to type (if not automated), and visually distracting. When I look at code, I want to see code that actually does something, or a comment that tells me something that was not already obvious beforehand. Reading stuff like "end if" just slows my eye down while I'm looking through real code. Also, it's not unusual for comments like this to get displaced during re-edits, e.g.

What happened here? Perhaps the while loop was originally a for loop, and was edited later - but the programmer neglected to change the comment. If that happens, the comment may be worse than no comment, because it's actively misleading people who rely on it. People changing this code must remember to change both the loop and the comment at the end. It's one more thing to think about that might go wrong.
[Stefan]: I posted a lot of sourcecode to the forum, allways using tabs. I didn't see a problem with the layout
Indeed, it may be OK if you don't indent too many levels. The problem is that there are many people, especially beginners, who create one long method without extracting any submethods. These same programmers also may not have learned when to break their lines up. So using tabs for indentation, in combination with multiple indent levels and overlong lines, greatly increases the chance that the code will be too long for many user's screens here at JavaRanch. I've had to edit quite a few posts that were screwed up this way. So I encourage everyone, especially newbies, to no use tabs when posting here.
[Stefan]: And the entire article doesn't focus on coding-style in context of the JavaRanch forum.
True. This was additional advice from me, specific to posting.
[ May 11, 2004: Message edited by: Jim Yingst ]
Barry Gaunt
Ranch Hand

Joined: Aug 03, 2002
Posts: 7729
One of the great things about the Cattle Drive Coding Convention is: you just gotta use it if you want your mooses!
Unlike the "standards" of many organizations it is an enforced standard. All companies I have worked for have never really enforced standards so maintenance programmers just insert code according to their own likes/dislikes.


Ask a Meaningful Question and HowToAskQuestionsOnJavaRanch
Getting someone to think and try something out is much more useful than just telling them the answer.
Jeroen Wenting
Ranch Hand

Joined: Oct 12, 2000
Posts: 5093
I've worked in environments where coding style was checked by automated systems.
Usually such are worse than nothing, checking such things as the exact position of fields in comment blocks, percentage of lines that are comments, etc. etc.
In this case, the coding standards even included naming conventions for method and variable names (not talking camelCase or hungarion notation but some homebrewn system in which all names had to be numbered sequentially throughout the file) that were meticulously checked.
Takes some getting used to but it's workable for simple layout languages like Cobol.
IMO as long as there is consistency in your work and you don't change the style of an existing file and keep to it when changing it even if it is different from your own preferences what exact variations you use don't matter much.
CamelCase is pretty much universally accepted in Java and laid down in the JLS itself which makes it IMO mandatory, but for all other things one should be pragmatic. Whatever makes you most productive, keep to it as long as it's readable...


42
Stefan Wagner
Ranch Hand

Joined: Jun 02, 2003
Posts: 1923

sever oon:
The tool 'diff' which is wellknown on linux, has the option to ignore whitespace. This is a first step.
But it ignores "foo" "fo o" differences too. Too bad. Doesn't know of java-syntax.
jeroen:
I observed, that in my eclipse-outline (a class-viewer), the following is much better readable:

than that:

but I guess I will stick to the standards in this point, because it exceeds the layout of the code.
In few years, perhaps they will lay it out like this:
getStreet
setStreet(String)
Jim:
when newbies use 8 spaces, the problem will be the same, won't it?
Most of them don't find the 'code'-button, as well as the 'coding style'-guide, but avoiding the super-long-lines in few cases might excuse this suggestion.
[ May 11, 2004: Message edited by: Stefan Wagner ]
Mike Gershman
Ranch Hand

Joined: Mar 13, 2004
Posts: 1272
Jim:
The "coop guide" says:
2.2 - Spacing
All identifiers are surrounded with whitespace.
Reasoning: Some utilities will cleanly select an identifier when you double click on it. Some of these double-click-functions are strictly space delimited, so any surrounding characters might accidentally get included in an otherwise clean selection. Therefore, whitespaces (spaces and newlines) are required around all identifiers.
int theTick=5; // NO! Double click would get "TheTick=5;"
int theTick = 5 ; // YES! Double click gets "TheTick"
if (theTick==5) // NO! Double click gets "(TheTick==5)"
if ( theTick == 5 ) // YES! Double click gets "TheTick"

The only time this can become a problem is with the loss of clarity in compound boolean analysis:
if ( ( hero == theTick ) && ( ( sidekick == arthur ) || ( sidekick == speak ) ) )
Rather
boolean isTickSidekick = ( ( sidekick == arthur ) || ( sidekick == speak ) );
if ( ( hero == theTick ) && isTickSidekick )
There are a few exceptions to this rule:
method names Tradition calls for all method names to be immediately followed by a left parenthesis

array dereferences Tradition calls for all array dereferences to be immediately followed by a left square bracket.
pre- and post-increment and decrement operators Tradition calls for the unary operator to be immediately preceded or followed by the operand.
cast operator Tradition calls for the cast to be written with no spaces

I find it hard to believe that significant numbers of working programmers would write:
y = funcA( 1 , 2 , 3 , 4 );

Putting spaces on both sides of the comma looks weird, defeats the attempt to have code look like math, is unlike any language or style I've seen, and is justified by reference to anonymous editors that obviously weren't even designed for Java.
Real Java editors such as supplied with NetBeans assist in indentation and in matching () [] {}, flag many errors, and use highlighting to mark reserved words, comments, etc. Why would anyone use a non-Java editor and ask people to use a strange coding convention to make up for the editor's deficiencies?
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
Mike: yes, I've read it. And? Why is this comment addressed to me? I'm not championing the Coop guide here.
Stefan: If newbies are using 8 spaces per indent and still write code that is too wide, there's not much we can do for them. The thing is, many people use editors with tabs set to 4, and don't realize that they'll be displayed at 8 when displayed elsewhere (such as here). Those are the people who are better off using spaces, IMO.
Jeroen Wenting
Ranch Hand

Joined: Oct 12, 2000
Posts: 5093
Stefan, for many people coming from C CamelCase naming takes some getting used to.
For people coming from Delphi it's a lot easier.
In a few years you'll agree with most of us that underscores do nothing to make code more readable, all they do is make names longer than they need be.
Now, when I see Java code that uses underscores for variable and method names I shudder in disgust almost as much as when I see C code that has the following (or similar):

which of course attempts to make C look like Pascal...
Mike Gershman
Ranch Hand

Joined: Mar 13, 2004
Posts: 1272
Jim:
I was responding to your post:
I was thinking intArray would be better, actually. And of course
int[] intArray ={10,5,7,-3};
is completely OK according to the Coop guide.

My point was that your example is not OK according to the strange rule I quoted.
John Smith
Ranch Hand

Joined: Oct 08, 2001
Posts: 2937
The JavaRanch coding conventions document does look like a draft. I especially enjoyed this one:

5.4 - Scope
All class attributes must always be private, except for inner classes.


I am sure what was meant is "Make the class attributes as private as possible", but the unsuspecting ranchers may think that "protected" is some evil C++ construct, and the "public static final double" attributes violate the OOP.
Regarding the formatting, I find the JBuilder auto-formatting feature very useful. Right click, and format. It formats code according to your specification. The spec can be exported and imported as a file, which makes it valuable in the team development. I am sure that other IDEs have a similar functionality.
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
My point was that your example is not OK according to the strange rule I quoted.
Ah, but it is. The only identifier in that line was "intArray", and it's surrounded by whitespace. Whitespace around literals, keywords, operators, and other punctuation like commas is optional. Except where required by the compiler. Don't ask my why, but that's how it's written.
Actually, I lied. All the intarray/intArray examples so far (including Paul's) do violate the Coop guide on one point. But it's not in section 2.2 on spacing.
Regarding spaces vs. tabs, I find it best to set my tabs to 8, because I often find myself browsing Sun source, and they use 8-space tabs there - but the indentation level is 4. So one indent level is 4 spaces, while two is either 8 spaces or 1 tab, and three is 12 spaces or 1 tab and 4 spaces. If you don't view this with 8-space tabs, it's very screwy. However I refuse to mix tabs and spaces myself (unless on a job that specifically requires it, which hasn't happened so far) and I view 8-space indents as overkill. So the only way I can view Sun source properly, and still get my own code to indent to 4 spaces rather than 8, is to use spaces exclusively.
Stefan Wagner
Ranch Hand

Joined: Jun 02, 2003
Posts: 1923

jeroen: I'm already using CamelCase. I only observed this to be less readable in the eclipseOutline window, especially when lots of setter and getter-Methods cross your way. Eclipse is of course not known to everybody.
In the rest of the code, underlines are indeed less readable.
And I disclaim every comparison between my CodingStyle and pascalism in C
A second drawback of this eclipse-window is, that it really opens the bracket sticking to the name (according to the rules here).
Traditions of programmers are very young, traditions of book-editors are over 400 years old. So they had some time in optimizing, but of course are generally using proportional fonts.
Their rules are: Brackets have a space to the outside, and no one in the innerside (exception: end of sentence: '.!?:' are followed immediately to a closing brace. Commas have a space afterwards, not before, which is very good readable too:

jim: I understand. I assumed again a tab-indentation-level of 8.
And you enjoy hitting 4-times space? Or is autoindentation allways working?
I often watch code-snipplets from the shell, where a tab is by default set to 8.
requiered by the compiler will perhaps mean

[ May 12, 2004: Message edited by: Stefan Wagner ]
[ May 12, 2004: Message edited by: Stefan Wagner ]
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
And you enjoy hitting 4-times space? Or is autoindentation allways working?
I've been using IDE's with autoindentation for a long time. Before that, I'd use an editor with the option to save tabs as spaces, and set the tab size to 4. So I could indent with a tab, but know it would be saved correctly. Now I often don't bother indenting at all; I just hit autoformat peridically.
Required by the compiler: yes. Another example is

All spaces above are required by the compiler. I'd prefer to insert one before the { as well, but the compiler doesn't care.
Marilyn de Queiroz
Sheriff

Joined: Jul 22, 2000
Posts: 9044
    
  10
Originally posted by Eugene Kononov:
I am sure what was meant is "Make the class attributes as private as possible", but the unsuspecting ranchers may think that "protected" is some evil C++ construct, and the "public static final double" attributes violate the OOP.

Good catch, Eugene. That should read "5.4 - Scope
All member attributes must always be private, except for inner classes."

When you feel the need to use "protected", you might be better off making the attribute private and use getters and setters.


JavaBeginnersFaq
"Yesterday is history, tomorrow is a mystery, and today is a gift; that's why they call it the present." Eleanor Roosevelt
Marilyn de Queiroz
Sheriff

Joined: Jul 22, 2000
Posts: 9044
    
  10
Originally posted by Jim Yingst:
I've been using IDE's with autoindentation for a long time. Before that, I'd use an editor with the option to save tabs as spaces, and set the tab size to 4. So I could indent with a tab, but know it would be saved correctly. Now I often don't bother indenting at all; I just hit autoformat peridically.

Ditto.
Warren Dew
blacksmith
Ranch Hand

Joined: Mar 04, 2004
Posts: 1332
    
    2
sever oon:
I'm saying that ALL unnecessary whitespace should be removed from code before it's checked into any revision control system. That should be part of the revision control system itself.
The problem with this is that people also use the source control system to store files where whitespace can be significant, such as HTML files.
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
Well, Sev did say code after all. It shouldn't be too difficult for a system to apply its formatting rules to .java files only (plus other programming languages I'd imagine). This doesn't seem like it should be a big deal.
I'd object to removing all nonessential whitespace from Java files, because sometimes it's used at the programmer's discretion, to add clarity by grouping related concepts together. If I write:

I probably meant to put that blank line between baz() and alpha(), because I think that the first three operations go together, and the last two go together, and grouping them accordingly will improve readability. So I don't want an automated tool to remove all the unnecessary whitespace, because once that blank line is removed, there's no way for any tool to reconstruct my original format. How would it know to re-insert a line between baz() and alpha(), but not anywhere else? Now this may not be a really big deal, since if I feel strongly that these methods should be grouped conceptually, I can always extract submethods using those groups. But that's more work. I feel nonessential whitespace can often add clarity (if not overused), and so I wouldn't want it taken away entirely. But I do like the idea of using automated reformatting to enforce a lot of standardization on what gets checked in; if not complete standardization.
Marilyn de Queiroz
Sheriff

Joined: Jul 22, 2000
Posts: 9044
    
  10
I think Jim meant:
 
 
subject: Documentation & Coding Styles
 
Similar Threads
a question about the ActionForm 's property type
What is coding studio?
create dll file
Adding blockID into select box from database by getting locationID from another select box
Struts best practices