Lair Of The Multimedia Guru

2006-05-19

Coding Style / Code Conventions

There are many coding style guides, IMO actually significantly too many … their existence often only justified by the single hypothesis that having everything in the same style is more readable then having one style per file and letting the original author / maintainer decide it, now maybe my memory sucks but i dont remember a single case where the difference in coding style in different parts of a project caused me any difficulty in understanding. It was rather the lack of any indention, exclusive use of single letter variables or simply the complexity of the code, lack of comments, and my stupidity of course which caused difficulty understanding something …

hmm, mphq cvs is still dead :( so lets try to write the ultimate coding style guide and hope mphq works when iam done so i can finally commit a few minor bugfixes

The ultimate coding (style) guide

Rule 1

Every rule must be justifyable and the justification must not apply to a contradicting rule too
yes, iam trying to avoid the “for consistancy” justification which can be applied to litterally anything

Rule 2a

Write consistant code / Changes should be approximately in the same style as the surrounding code
Justifiction: having the coding and indention style change every few lines makes code somewhat harder to read, while a overly strict style restriction will cause some volunteers (or employees) to leave

Rule 2b

Write indented code (code within a block should be at the same indention level, code in parent and child blocks should be at different levels), placement and indention of stuff like {} is not restricted here, just the actual code
Justification: see mplayer.c for what happens without that rule :)

Rule 2c

Avoid constructs which IDEs/editors have difficulty with, common examples are non-ASCII letters, tab / space mixes, differing tab length in different files, dos line endings, …
Justification: obvious

Rule 2d

avoid non english (in identiers and comments)
Justification: not everyone speaks every language, english is understood my most people, of course if every programmer you care about understands hungarian then its a perfect choice too

Rule 3

maximize usefull information at minimum size and complexity (simple code preferred)

so a variable name like szMyCompleteName is normaly worse then simply name as the type is probably obvious, “complete” also adds no new info … of course a function which converts zero terminated strings to length + chars style would benefit from having the type in the names, it all depends upon how and where a variable is used
comments should not say whats already obvious from the code like int i=sqrt(v); //i is the squre root of v but instead provide usefull info like //i is the largest factor v can contain, so we only need to test integers less then i but then in that case maybe renaming i to largest_factor would have provided more info at less size …
justificaion: the idea is to provide the reader with the info she is interrested in, not to duplicate and spread out the important stuff between noise
also less code means fewer places where a bug could be
Note: this rule also forbids code duplication, and other bloatedness

Rule 4

Write efficient code
Note: efficient here means little memory, disk, cpu, …
Justification: well this one should be obvious

Rule 5

Write portable code
Justification: well this one should be obvious too

Rule 6

Write localized / internationalized applications (user vissible stuff in her native language)
Note, maybe error messages should be dealt with differently as the developers need to understand them in bugreports …
Justification: well this one should be obvious too

Rule 7

Write compatible code (dont break compatibility of file formats, your last library release, …)
Justification: well this one should be obvious too

Rule 8

Write secure code (dont write over the end of an array, checking untrusted input carefully, be carefull with malloc(w*h) due to overflows of the *, …)
Justification: well this one should be obvious too

Rule 9

Write modular code / split code into independant parts
Justification: many dependancies makes code very hard to understand and maintain

Rule 10

If some rules contradict, use common sense (which goal is more important in a specific case)

Filed under: Off Topic — Michael @ 19:49

6 Comments »

  1. I think FFMpeg is violating Rule #7 with non-stable API/ABI, don’t you agree? :-)

    Comment by cartman — 2006-05-21 @ 19:44

  2. well …. maybe …. very rarely ;)

    Comment by Michael — 2006-05-21 @ 20:54

  3. Apparently most of the rules which “should be obvious” are not obvious to GNU developers. Maybe you need to come up with better justifications and mail those to them… :)

    So it doesn’t just look like I’m trolling.. in particular they take #6 and 7 to the extreme at the expense of #3, 4, 5, 8, 9, and IMO 10 as well since they didn’t use common sense about what to do when rules conflict. :)

    Comment by Rich — 2006-08-02 @ 08:15

  4. Rule 4 is rather dangerous…. and should probably be tempered by adding “but never optimise early”. It could be argued that the rule refers to a design rule rather than a purely coding one. Keeping code simple statistically means fewer bugs. It is also worth bearing this in mind before going to great lengths to follow rules 5 and 6 – show me a portable directX application. Trying to get a customer to pay more for a product which does nice things that they will not use just isn’t going to happen. Finally, I totally support the spirit of rule 9 but this has to be driven by modular designs. Maybe change that to “buy and read the design patterns book” :-)

    Comment by Steve — 2006-10-13 @ 01:15

  5. Hi all!
    You are The Best!!!
    G’night

    Comment by Terabanitoss — 2007-05-05 @ 00:08

  6. Attention Sir/Madam
    I am Dario Roberto Santos, President MP DO Brazil Ltd.
    Sao Paulo, Brazil. We are top dealers of your product in the Brasilia market.
    One of your customers who is in same line of business with us recommended your
    company to me when I met him in trade fair some time ago and I have
    decided to give your company a trial. Kindly send quotation of you company product FOB.

    Please kindly reply ASAP

    Street Address,
    Alameda Santos.
    211 salas 1001/1002.
    Sao Paulo. Brazil.
    Zip Code, SP 01418-000.
    Telephone, 55 11 3171 3342

    Comment by Robertos Santos — 2018-12-19 @ 07:02

RSS feed for comments on this post. TrackBack URI

Leave a comment

Powered by WordPress