Win a copy of Re-engineering Legacy Software this week in the Refactoring forum
or Docker in Action in the Cloud/Virtualization forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Code conventions & design doc size

 
Patrick Cobbett
Ranch Hand
Posts: 44
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi all, i have a couple small queries so i've slung them together.
Firstly, i follow all the proper coding conventions but is code style considered part of the proper coding conventions? When i talk about code style i am specifically talking about how curly-brackets are placed.
I write code like this:
public void doThis(){
// code
}
for(int i=0; i<size; i++){
// code
if (true){
// code
}
}
However, most code i see is written like this:
public void doThis(){
// code
}
for(int i=0; i<size; i++){
// code
if (true){
// code
}
}
Does it matter which way the brackets are placed as long as they are consistent or is the second the proper way it should be done? Does anyone share my style of code?
And my second question is my concern about how much to write for the design document. I don't want to bore the marker to bits and have him get irritated if i point out points which may be obvious. In the URlyBird assignment i think alot of marks are awarded for this, by in mine, FBNS, there is very little in comparison. Is the design document mainly to help the examiner understand the program, or it is assess my abilities at documenting it? Sun told me NOT to go over-board on this.
If people aren't sure then chuck in a small post indicating how much you have or intend to write for it. I just wanna get a feel for how much people are writing for this.
 
Patrick Cobbett
Ranch Hand
Posts: 44
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The indents were ommited when i submitted my last reply, lets see if this works:

My code:

Other code:
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 11854
185
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Patrick
I have heard several people saying that we must follow Sun's Coding Conventions. According to that document your second example is the more correct one (still doesnt have the correct white space though).
I cannot find anything in the instructions that state this though, so I don't know how mandatory it is (or isn't).
The nice things about using the Sun standards are that there are some nice tools around that can programatically check your code to ensure that you are adhering to that standard. Checkstyle is the one I use. You can configure this (and presumably other) tools to meet your coding style, but if you use the Sun style, then the configuration is already done for you.
As for design choices document - I went overboard. You can see what I did in this post. I got 100% for documentation, so going overboard didnt hurt.
Regards, Andrew
 
Damian Ryan
Ranch Hand
Posts: 117
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I tend to agree with what Andrew has said, but would reiterate that use of Sun's conventions is not mandatory (though perhaps the safest plan).
There are a couple of things I don't like about Sun's conventions so I tend to go my own way on those, because that's the way I've been writing my Java code for years now. I didn't lose any marks for not following Sun's conventions to the letter.
I think that what is most important is that your code formatting is consistent across all your sources.
I know a lot of people use Checkstyle (mentioned by Andrew above) but I'm quite fond of Jalopy which I use as a plugin with NetBeans. It is also usable standalone, and as a plugin for several other IDEs (such as Eclipse, JBuilder, jEdit and JDeveloper).
[ July 25, 2003: Message edited by: Damian Ryan ]
[ July 25, 2003: Message edited by: Damian Ryan ]
 
Mark Spritzler
ranger
Sheriff
Posts: 17278
6
IntelliJ IDE Mac Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Patrick, your other code looks more to the standard. It is funny because where curly braces are can really just be a personal preference. I mean opening curly braces on the same line, or on the next line. Closing braces tabbed in, not tabbed in.
I think the point of the standards are not to push their will onto programmers, but to make uniformity with all coders.
It is usually just a matter of getting used to the way the standard looks. At first you will be like, "Well, I don't like the way that looks". But after you get used to the standard you will feel the same way as to the look as you might do now with how you do it now.
Mark
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic