aspose file tools*
The moose likes Java in General and the fly likes Coding Standards Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Java in General
Bookmark "Coding Standards" Watch "Coding Standards" New topic
Author

Coding Standards

Saurabh Agrawal
Ranch Hand

Joined: Oct 07, 2003
Posts: 244
Hi folks,
I want to design a coding standard document for my project.For this i have already seen lots of material on google and finally came up with some fields which are as follows.But i want to add more details to the same? So can anyone suggest me what can be further added to these table of contents:

Any help would be appreciated.Please let me know.

Current contents are :

1The Most Important Rule of Coding Standards3
2Why Standards Are Critical4
3Naming Conventions5
3.1File Names5
3.2Package Names5
3.3Class Names5
3.4Interface Names6
3.5Method Names6
3.6Constructors and Destructors7
3.7Variable Names8
3.8Member Variables8
3.9Local Variables9
3.10Exception Handling9
3.11General Naming Conventions11
3.11.1Enumerated Types (Arrays, Vectors, etc.)11
3.11.2Final Local Variables12
4Formatting13
4.1General13
4.2Control-of-Flow Statements13
5Comments15
5.1How to Javadoc your code15
5.2Classes and interfaces15
5.3Methods16
5.4Member Variables and Constants16
5.5Other recommendations16
5.5.1Which type of comment and when16
5.5.2Multi-line comments17
5.5.3Single-line comments17
5.5.4Reminder comments17
5.6Presentation Framework Documentation17
5.6.1Event Handlers17
5.6.2Modelers18
6Access Protection to Methods / Member Variables19
7Class Design20
7.1Design Tips / Hints20
7.2How Much Code for One Method20
7.3Order of Declarations21
8Language-Specific Pitfalls and Guidelines22
8.1Evaluation / Assignment Operators22
8.2Constructors22
8.3Finalizers22
8.4Abstract Classes22
8.5Reflection22
9Naming Enterprise Java Beans, Servlets, and JSPs23
9.1Enterprise Java Beans23
9.2Servlets23
9.3Java Server Pages (JSPs)23
10Common Mistakes from Code Reviews24
11A Point of View on JSP Coding Standards25
12References26


Success is not doing extraordinary things but doing ordinary things extraordinarily well.
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
That's a big job you've laid out. A few years ago I bought everyone on the team a copy of Elements of Java Style (about $11 a head) and wrote one page of exceptions and additions.

Nowadays our coding standards web page starts with this:

Quality code:
* Passes tests
* Expresses intent
* Has no duplication
* Few classes & methods

each of which is a link to more discussion.

Code formatting is a piece of cake with modern IDEs. The best thing to do with comments is make them unnecessary. There's not much left after that.


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
John Smith
Ranch Hand

Joined: Oct 08, 2001
Posts: 2937
Many of the items that you've identified are covered in Sun's Java Coding Conventions
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
What is your *intent* of writing that document?


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Rick O'Shay
Ranch Hand

Joined: Sep 19, 2004
Posts: 531
Screw the coding standards and deliver a successful code base. That means continually refactoring to make your classes and methods more general where reasonable and then specializing in, well, specific methods and classes. So the result is a re-usable well structured software asset. Apply separation of concerns and other useful principals and leave the coding standards to automated formatting tools.

Hook up your version control system (if you're not using one forget coding standards and get the basic tools first) to a pretty printer. These are, oh, twenty or thirty year old tools that force conformance of input files. If the author did not apply the pretty printer don't allow the check in. Do not format automatically, that's like giving the chicken seed for looking at the push pad, make sure they press it.
Rick Portugal
Ranch Hand

Joined: Dec 17, 2002
Posts: 243
I'm not sure that "screw the coding standards" is the best advice I've ever heard. There is value in standardizing the way your developers handle exceptions, name packages and classes, etc.

I'm interested in your "Constructors and Destructors" section. Did you steal this format from some C++ standards? There are no destructors in Java.


IBM 286, SCJP, SCWCD, EIEIO
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Rick Portugal:
I'm not sure that "screw the coding standards" is the best advice I've ever heard. There is value in standardizing the way your developers handle exceptions, name packages and classes, etc.


I agree that there is a lot of value in a team-wide coding standard. I don't think, though, that there is much value in a *coding standards document*, especially not if its as complex as outlined by the original poster.

In my experience, it's much better to have the team come up with its own standard over time by discussion and collaboration.
Saurabh Agrawal
Ranch Hand

Joined: Oct 07, 2003
Posts: 244
Thanks everyone for active suggestion and partipation in the coding standards discussion.

I have finally formulated the document and it is all set as per your varied suggestions.


Thanks everyone once again,
Saurabh
Rick O'Shay
Ranch Hand

Joined: Sep 19, 2004
Posts: 531
Originally posted by Rick Portugal:
I'm not sure that "screw the coding standards" is the best advice I've ever heard.


Perhaps not but I am certain you did not read past that opening statement. The suggestion was to let formatting tools handle the mundane and other wise using peer reviews to quickly establish what's acceptible.

The formatter will dictate style and frequent reviews will ensure that code structure adheres to well-known best practices. An exhausted stipulation of coding standard details is utterly misguided IMO.
Rick Portugal
Ranch Hand

Joined: Dec 17, 2002
Posts: 243
Not sure how you could be "certain" of what I have read. I read your opinion and I diagree with it. "Quickly establishing what's acceptible" is great, but it should be written down.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Rick Portugal:
"Quickly establishing what's acceptible" is great, but it should be written down.


What for?

In my experience, the important part about a coding standard is that it gets followed. For that, it needs to be in the heads of the team members. Having written it down in a dozen pages document is hardly a good way to get it into the heads, in my experience.

We have a quite good coding standard that got refined over the years, driven by our needs. Nothing of it is written down anywhere, and I have no clue what it would be good for.
Rick Portugal
Ranch Hand

Joined: Dec 17, 2002
Posts: 243
What do you do when a new team member comes on? What happens when there is a dispute about what the standards are?
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Good questions - thanks for asking!

Originally posted by Rick Portugal:
What do you do when a new team member comes on?


Well, first of all, he will get the Eclipse configuration file for the code formatter. He will also be told that we mostly follow Suns coding standard, that our interface names all start with a capital I, that besides this one we don't use any prefix notation and that we try to replace comments by expressive code as much as possible.

Other than that, I define "team" by close collaboration. By close collaboration, he will simply pick up the existing coding standard during his daily work - by reading existing code, by getting his code peer reviewed, by pair programming etc.

What happens when there is a dispute about what the standards are?


A standard is defined by what the team does. When there is a dispute, it gets discussed until consensus is reached. The result of the discussion becomes the standard.
Rick O'Shay
Ranch Hand

Joined: Sep 19, 2004
Posts: 531
Originally posted by Rick Portugal:
What do you do when a new team member comes on? What happens when there is a dispute about what the standards are?


The new team member formats the code using the formatting tool. That way, even if they are too thick to realize they should adopt the style staring back at them on every page of code, it will still be formatted correctly.

In terms of disputes, a managager or the project leader stipulates a style and that is imposed in the formatting tool. End of story. If a particular issue is unclear or unspecified, pick one and next time you have a meeting casually throw out a question.

If you find a programmer is stressed or obsessed over coding standards over and above applying a formatting tool and common sense, consider it an opportunity to simplify your downsizing effort.

Let automated tools handle it and focus on structure, constant refactoring, generalization. You know, important things. Screw the coding standards.
Rick Portugal
Ranch Hand

Joined: Dec 17, 2002
Posts: 243
My last post on the subject...

Obviously formatting is only one small part of coding standards. IDEs don't enforce package naming standards. There is a standard at many companies that says that methods which return boolean values should start with "is": isFound(), isProtected(), etc. No IDE enforces that. No IDE enforces that getters and setters should be called getX and setX. "Using the formatting tool" doesn't help. Written standards do.

I worked at a company where a consultant delivered a system that used hungarian notation throughout. We didn't want that, but how can you criticize him if you have no written standards?

Of course it makes sense that "the result of the discussion becomes the standard," but doesn't it make sense to document that standard for future developers? Arguing against written standards is really arguing against the written word.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Rick Portugal:
My last post on the subject...


That's a pity - I always learn most from discussions with people who disagree with me...

No IDE enforces that getters and setters should be called getX and setX. "Using the formatting tool" doesn't help. Written standards do.


No written standard can enforce that, either. I even think that if a standard needs to be *enforced*, there is something wrong with it, or with the team.

A standard needs to be *lived* by the team. And for that, it doesn't need to be written down. It needs to be in the heads of the developers, and a written document isn't the best way to get it there.

I worked at a company where a consultant delivered a system that used hungarian notation throughout. We didn't want that, but how can you criticize him if you have no written standards?


You certainly should have communicated to him what you expected from him. Could have asked him about his preferred coding standard and then simply told him "please, no hungarian notation"? How much do you need to write down for that?

For a collocated team, what I assumed the original poster might have asked about (he unfortunately didn't reply to my question), a document isn't necessary at all, and doesn't even help much, in my experience.

Of course it makes sense that "the result of the discussion becomes the standard," but doesn't it make sense to document that standard for future developers?


Only if there aren't better means to communicate the standard to them. In my experience, there typically are.


Arguing against written standards is really arguing against the written word.


Well, yes - in this specific case I think the written word *is* inferior to the alternatives. There are much more rich communication channels than the written word, face to face conversation probably being the richest one. So if we can use the latter, I'd prefer that very much.

I highly recommend reading "Agile Software Development" by Alistair Cockburn on the topic of communication in software development teams.
[ July 28, 2005: Message edited by: Ilja Preuss ]
Rick O'Shay
Ranch Hand

Joined: Sep 19, 2004
Posts: 531
Originally posted by Rick Portugal:
My last post on the subject...

Obviously formatting is only one small part of coding standards. IDEs don't enforce package naming standards. There is a standard at many companies that says that methods which return boolean values should start with "is": isFound(), isProtected(), etc. No IDE enforces that.


True, some things are so child-like in their simplicity that no enforcement is required. Pick an existing convention and and follow it but don't let your karma run over your dogma. Focus on the important things and assume any idiot can follow a few simple rules brought up during code review. You do have code reviews do you not?

Having said that, I am happy to report that naming convention enforcement definitely is automated in many code prettificationilizers.
Rick O'Shay
Ranch Hand

Joined: Sep 19, 2004
Posts: 531
Originally posted by Stan James:
There's not much left after that.


No offense but why are arguing against the written word with that icon?



 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Coding Standards
 
Similar Threads
coding standards
java coding stipulation
Java coding standards
confused...
tools to check quality of Java