Deprecated: Function split() is deprecated in /home/tbriggs/public_html/s9y/plugins/serendipity_event_metadesc/serendipity_event_metadesc.php on line 101

Tom's Third Law: When in Rome, Do as the Romans

or Have Good Coding Standards

Laws don't get any more straightforward than this one. If you're making changes to a piece of code that someone else has written, make your code look like theirs. Use the same naming conventions, formatting conventions, design conventions, language constructs... everything.

This benefits:

a) The original author, who will probably end up being responsible for your changes
b) All subsequent readers and modifiers, who won't have to decipher two different coding styles to read one piece of code
c) You, who will be less likely to break something

Anyone who has developed software professionally has at least seen this law broken. Odds are good that they've broken it themselves, for that matter. But the first time you have to look at code that has been touched by different people with different coding styles you learn how frustrating it is when people don't follow this rule.

Imagine a document where the first paragraph were written by an American, the second by a Brit and the third by an Australian. Is it all English? Of course. Would it be easier to read if you didn't have to change contexts and vocabularies with every paragraph? Of course.

This concept applies not only to coding style, but philosophy and tools as well. If the program you're working on is written in an old-school functional style, don't force objects into it - just modify the functions. If the application makes heavy use of SQL to manipulate and retrieve data, don't start adding functions that retrieve raw data and manipulate it in code - just write some more SQL. And if the program you're working on uses a certain toolset - database connectors, loggers, etc. - use the tools that are already there. Don't add new ones. And whatever you do, don't write new ones.

Quick story: I worked on a system not long ago that used three different logging subsystems. Why? Three different people, who each had their own personal logging system preferences, had worked on the app. The last two had decided to integrate their logger of choice rather than use the one (or ones) that was already there. Was there plenty of logging in the application? Yep. Could you practically control and use the logs the system produced? No, because each sub-system had it's own configuration, it's own message levels, it's own output format, etc. This is admittedly a pretty extreme example, but it makes the point rather nicely: if all three developers had used the same logging system, the system's logging would have been phenomenal. Instead, it was utterly useless (and, in fact, was a hindrance rather than a help).

I bet you don't have to think very hard to recall a similar mess in an application you've worked on. Consider yourself lucky if you can't.

In some ways - particularly concerning tools - this is a corollary to my second law. If you're re-using what's already there, you're being properly Roman. If you're not, well... you'll eventually get thrown to the lions.
Trackbacks

Trackback specific URI for this entry

For longer than I care to remember, I've been writing joins like so: SELECT col1, col2 -- Boo on "SELECT *"! FROM T1, T2 WHERE T1.x = T2.x Over the last six months or so, however, I've found myself forced to used outer joins (which are evil, b
Comments
IMO this law has at least one exception. Imagine yourself working on a legacy code (by modern definition the code without tests). There is a book about this situation called Working Effectively with Legacy Code. Reading this book, I think it is crucial to write tests (even if you are first Roman who ever did that). It is almost always better than 'code & pray' technique.
I agree wholeheartedly that you should never commit (whatever that means in your particular environment) anything that hasn't been tested and that doesn't have a good reproducible test. I think that's a bit outside the "make your code look like theirs" concept though - you should make the changes in their style and write the tests in yours. Good point though.
Add Comment



Enclosing asterisks marks text as bold (*word*), underscore are made via _word_.
Standard emoticons like :-) and ;-) are converted to images.
E-Mail addresses will not be displayed and will only be used for E-Mail notifications.