It is very important for code readability and understanding to use the same coding style across all files of an application. It is even important to have the same coding style in all your source code.
Having the same coding style helps reading the code. And if you carefully select your coding style, you can even pinpoint coding errors simply because something look strange in the layout.
Of course, if you share your code among a team, like I do, it is very important that everyone in the team uses the same coding style. it is even important that in a company, all development teams use the same coding style so that code can be easily read and shared across teams and developers.
What coding style to use? I would say that this is mostly a matter of personal preferences as long as the style is constant and emphasizes the code structure.
I wrote my personal preferences in a document titled "ICS Coding Style". The name comes from the fact that I wrote it long time ago when a lot of peoples started to make changes to ICS. I wanted everyone to use the same coding style as me. Not an easy task because every developer think his coding style is the best.
The following image gives an idea of my coding style.
You can download my coding style document from here.
There are many "code formatter" on the market. The IDE is use (Delphi) has a fairly powerful code formatter. But this is not enough. For example, no code formatter will be able to rename the variables, methods and other identifiers according to a naming convention. Nad properly naming identifiers is an essential part of the coding sytle.
Code formatter also doesn't handle all aligments. For example, when the code must be broken into several lines, the code formatter will mostly go to the next line with some indentation. i prefer to aligne arguments and this become problematic for the code formatter when arguments are themself function calls.
Follow me on Twitter
Follow me on LinkedIn
Follow me on Google+
Visit my website: http://www.overbyte.be
This article is available from http://francois-piette.blogspot.be
13 comments:
", source code layout is simply ignored by the compiler. You can write as you like."
this could arise the impression that the compiler as such would have to have code prettifying functions, but in most cases imho i think this should be the job of a code analyzer or code prettyfyier
I agree, it is important, but it involves more than formatting and naming. It also involves implementation style. Like the use of interfaces, or if you use class helpers. Basically there are many small technical decisions we make in our code. It is great if the while team agrees on which choice to make ahead of time. These types of styles are best shared through code reviews and pair programming where the decision process can be discussed. Although books like Nick's and Code Complete are good conversation starters.
"Indentation is by 4 spaces"
Why 4 spaces? 2 is more readable, and it looks better.
Code styling is infact very important if you work in a team. But I am very disappointed that you prefer a non-"Delphi-Source" standard formatting - it is very important that all delphi source (be on the web, be in vcl classes) looks the same: First because of all the beginners struggling with different code styles found ont the web and thus creating their own "style" and second the endless discussions on which formatting is the "best"/ the one the company should use for a project. I am really tired looking at code formatted like you do, just because it reminds me of every single new coder that thinks his indentation is "the only right way" of writing code, even though there is a well-known standard: take a look at the vcl sources...
I really don't understand why most developers prefer to write keywords in lowercase. I think it's better to write them uppercase, I read them better even using syntax highlighting.
I agree it is important, and being consistent within a team is essential. I also agree with Jim that it's about implementation style too though - although there does need to be some flexibility, because different people think differently and implement things differently, which is a strength of having varied people in one team.
I'm curious about some of the choices in your style guide. For example, why do you align variable declaration types? (I personally find that really hard to visually scan.) And just out of curiosity, why a four-space indent?
I also saw you use old-style comments because you need to compile with Delphi 1. Only one response to that: wow.
About the old style comment. I don't use it anymore. Its simply that the document is old.
About the 4-space indent: I find the indentation more visible with that and I'm somewhat forced to rewrite the code so that not too much indentation take place and that is a good thing for clarity.
About keyword in lowercase: I am among those who like to use lowercase for keywords. Using uppercase make them to be to much visible imo. But that's a matter of taste of course.
Thanks for sharing your style, I agree that style is very important. I especially like your emphasis on alignment, so often I see code that is inconsistent in whitespace usage.
FWIW, I might recommend a few things with regards to the sample code:
- There are quite a few abbreviated variable names, I avoid abbreviations unless it's a very ubiquitous term. For example "Value" which seems to maybe be a "PixelValue" or just "Pixel"? "MaxIter", "ColorDiv", "ColorOff", "F", all of these make this code difficult to follow :(
- ColorMadelPoint... might be better as ColorMandelbortPoint
- ColorInside... whenever I see comments to explain a variable, I think that's usually an indication that the name needs some rethinking
- ColorMandelPoint2 - trying to guess what this method does is very difficult, the name doesn't give any clues :(
- Subtle point but instead of A/R/G/B (and I know this might not be from your code), but I'd say why not have Alpha/Red/Green/Blue instead? If you see all these together it will click ARGB but if these were individually accessed in different parts of the code I would probably be confused.
- Frac, maybe a better name would just be FractionalPartOfPixel? And the comment about the method should probably go on the method itself so all consumers can see that when using the method.
- ColorLog and ColorLogFact - I don't know if these are abbreviated or not, I assume they might be?
There are 10 good conding styles ... let's consolidate them to one consisten universal one ... there are 11 good coding styles...
I think using a really good coding style is mandatory to write consistent and high quality software - you need to keep your kitchen clean if you want to serve high quality food. But I also think you should NOT invent a new one if there already is one unless you can become the leading one.
For C# we have StyleCop enforcing coding guidelines.
I'm not really familar with Delphi - What style is your style based on? How does it relate to Object Pascal Style Guide? Do you have tools that can check for the rules? Can you include such tools to the build process so you can have a build break in a continous integration build when violating the rules?
There is only *one* valid code formatting: just take a look at the official sources.
The argument "I am using 4 spaces because ... I find the indentation more visible" is invalid: if you're used to read code with 4 spaces then a 2 spaces indent is hard to read, where as if you're used to read coded with 2 spaces then a 2 spaces indent is hard to read. Just a matter of usage. Believe me. As a MVP you should follow the "official" rules - try it! After some days you won't find a 2 space indentation irritating. for sure.
I settled on the default coding style proposed by the integrated code formatter. Not my preference and has some shortcomings (fluid interfaces end up looking like crap) but it is good enough.
As for tabs/spacing... consistency is all that matters (perhaps base that consistency on the platform). And at the end of the day, any DECENT IDE can alter how this is displayed :)
Post a Comment