• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Coding Standards

 
Ranch Hand
Posts: 244
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
 
(instanceof Sidekick)
Posts: 8791
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 2937
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Many of the items that you've identified are covered in Sun's Java Coding Conventions
 
author
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
What is your *intent* of writing that document?
 
Ranch Hand
Posts: 531
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ranch Hand
Posts: 243
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Ilja Preuss
author
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
Posts: 244
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 531
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
Posts: 243
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
Posts: 243
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 531
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
Posts: 243
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
Posts: 531
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
Posts: 531
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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?



 
If you try to please everybody, your progress is limited by the noisiest fool. And this tiny ad:
a bit of art, as a gift, that will fit in a stocking
https://gardener-gift.com
reply
    Bookmark Topic Watch Topic
  • New Topic