Slashdot Mirror
What Workplace Coding Practices Do You Use?
Agent_9191 asks: "Recently I've been promoted to what essentially amounts to a project lead role for every project we do, in house. Since my company has run for the past 35+ years with no form of central IT department, there has been no standards put into place for developers to abide by. One of my tasks is to set up standards in how projects will be implemented and produced. Right now I'm more concerned about trying to set up coding standards, so that any developer can jump into any part of a project and be able to figure out what's going on, without wasting a couple hours just to figure out the code. I've come across some documents in this area from a few sources (of course can't remember them off the top of my head). What practices/standards do you use in your workplace?"
Has several excellent articles on the subject This is about as good of a starting place as any.
SJW: a person who perceives an injustice, and while correcting it, commits a greater injustice.
And make sure they update comments if changes necessitate it. There's nothing worse than reading through a function's description, complete with well-documented inputs/outputs/conditions/etc. and finding out that those things no longer apply because somebody changed a 1 to a 2.
on this particular subject. i believe code complete 2 came out "reasonably recently". that said, were this my task, i'd say the following:
1) document things thoroughly using a tool like doxygen. there is no excuse for interfaces not to be thoroughly documented
2) adopt a standard naming convention. in java, this is easy -- just use the default. in other languages, you'll probably have to make your own up.
3) pick an indentation style. it really doesn't matter which since tools like indent can convert between them almost painlessly. all code that goes into the repository is run through indent to put it into a standard format
4) require that code compile cleanly with no warnings at the most anal retentive compiler settings before it can be checked in unless there are good reasons to ignore the compiler warnings
5) average devs are only able to commit to the "head" fork (or equivalent in your sccs). the code is not committed to the "real" fork until it passes whatever tests you have
6) incorporate tools like valgrind into your testing cycle --- they should come back largely clean. if they don't, things need to be fixed unless there's a really good reason not to.
7) people who check in code which breaks cvs or, upon a code review, are found to not sufficiently adhere to your guidelines owe their dev group donuts.
Is this supposed to be a joke??! Both of them are worst comments, because they only formulate in english what the code already says by itself. Everyone can see that this is an if-statement, everyone is able to identify the condition, and everyone knows the semantics of an if-statement.
A good comment is not describing what is done (since everybody can see that from the code itself), a good comment describes why something is done, or what the overall objective of the statement is.
For example:
This is ways more useful. Even more useful would be to already use self-describing symbol names in the code itself, like
Windows is like decaf - it tastes like the real thing, but it won't get you through the day.
without wasting a couple hours just to figure out the code.
A couple hours???
Look, no offense, but you either only deal in "toy" code, or you have such high expectation that you will fail, and quite spectacularly.
A new coder, even an experienced one, takes days or even weeks after coming into an existing project before he can contribute anything but the most trivial of changes. For a truly massive project, or one that requires intimate domain-specific knowledge in a niche industry, extend that to months.
If you can find a way to get an unfamiliar newcomer up to speed on any "real" project in a matter of hours, consider your talents wasted in your current position.
Amen to that.
In addition to the original comments being redundant, there's also the issue of the code and the comments getting out of sync...
The company I work for just wrote up a formal coding standard, which includes everything from a guide to our internal hungarian notation, indentation guidelines, and even which C++ features/paradigms are supported, frowned upon, or not allowed. All the coders got a chance to send in feedback before it was finalized, and we even ended up with a list of recommended reading on the subject, including:
The idea is to keep the code readable and maintainable with the least amount of re-invention of the wheel. With good coding practices, it's easier to avoid bugs in your own code and spot them in others (reviews are also a big plus on both counts). And it gets any religious battles out of the way up front, so you don't have to waste time bickering later on.
C# - The C# Coding Style Guide, Mike Krueger(SharpDevelop). This is probably the most widely used one (Novell). It largely agrees with Microsoft's internal coding standards, with a few exceptions. .Net Coding Standards, part of the SDK. This is not comprehensive though, like the C# doc mentioned above.
VB -
Version Control -
Server: Subversion + Apache
Client: Tortoise SVN (Excellent) [We also use Perforce, CVS, VSS(Commercial apps)]
Continuous Integration - Cruise Control.Net
Intranet, Knowledge Management - DotNetNuke (www.dotnetnuke.com)
Project Management - dotProject (PHP) (www.dotproject.com), MS Project
Unit Testing - NUnit (www.nunit.org)
Life is just a conviction.
Snowden and Manning are heroes.
"I once came across a ~1400 line function"
This is so fucking wrong and wicked the programmer who did it should go straight to hell. I'm sure there's no functional coesion in there: most likely there are many disparate tasks that should be each in its own function and called from there. I'm sure there is a lot of cut-n-paste in there that should be each in its own function and called from there.
I'm sure you can guess where i'm willing to get to... more important than hungarian notation, comments or documentation in PDF format is abiding for these 2 simple rules: KISS -- keep it simple, stupid -- and DRY -- don't repeat yourself. Once you do it, coding and reading code is a lot easier.
So, my advice:
* Give meaningful names to important, global, business rules variables ( local variables like i or c are ok, since they are mostly irrelevant ) or functions/methods/procedures/subroutines
* Write short, highly coesive functions/methods/procedures/subroutines
* Stop the cut-n-paste madness! If you do it a lot, it's obvious the copied code if begging to be parametrized and be given a name. Programmers altering your original code will be thankful
* Write modular code, not a plain, huge, stupid monolithic wall of letters. Even in languages with no namespace support ( C/PHP etc ) a good naming convention for functions of a certain module/header can do wonders...
* and please: meaningful names don't mean phrase-like names like thisLocalVariableIsCool. Conciseness go a long way towards good readability...
I don't feel like it...