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?"
Tell them to use comments in code, and be sure that they make them good comments.
I don't preview or spellcheck.
GetOuttaMySpace - The Anti-Social Network
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.
- Get a development database, a testing database and production database. Yes, you need all three.
- Write a few docs explaining each system. Make these are detailed as you possibly can. (This will save you weeks in the long term)
- Use software revision control. CVS, VSS, whatever, use one.
- Use a bug tracker. BugZilla, Jira, CityDesk, whatever, use one.
- Use whatever coding standards the language reckons you should. If java, use sun's standards. If microsoft, use their standards.
- Write automated unit tests. I don't care if you're not an agile or XP developer, write unit tests. Check out Junit, or Nunit, or just write your own.
- Setup some code so that you can check out ALL code from the source code repository and compile it by ONE COMMAND. Eg, "make" or "ant" or "maven" or whatever. This will take time but is worth it.
- Have a naming standard for database tables. This will make your life SOOOO much easier.
- Read thedailywtf.com and don't do anything that is posted there.
- Write specs for your new developers. Please write specs for your new developers. Don't just say to them 'fix this up'.
- Make sure code isn't hard-coded to a particular directory. Everyone does this. Fix it. (Might be part of step 7)
- Create your own standard config files.
- Have code reviewed by peers. Don't be a bastard but be nice when picking on people's code.
- As mentioned, comment your code but use the language standard. Java - javadocs, Perl - perldocs, etc. These are cool, but don't get too carried away. Nothing can replace a good spec.
- Ignore what most people say on Slashdot. (Except for me, of course).
That'll keep you busy for a couple of months! Doing thiswill make you well on the way to having a pretty high level of coding quality. Most companies don't do all of them. Good luck.Yeah, but Joel's an ass. Have any of his worshippers here on /. actually *used* something written by Fog Creek or whatever? FogBUGZ, a web-based bugtracker, seems to be his one claim to fame, & it's terribly mediocre. I mean, mostly it works, but the search function doesn't, the UI is inconsistent, & while you can define filters (such as, "my open priority-1 bugs"), you can't share them, which makes them nearly useless. Joel writes a good spiel, but when it comes to coding, his company ain't the shit.
Plus, he argues passionately for paying programmers well & giving them exciting projects, but in at least two cases he hired interns to start his company's most interesting apps.
Dude needs to work on his street cred.
The moral of the story?
A. You are not the font of wisdom. If very lucky, you are the point of the pen. Rule carefully.
B. Don't make standards based on what you learned in school. Base them on what you learned in real life.
C. If an Old Fart tells you that one of your edicts is stupid, don't assume that they're resistant to change just for the sake of being crotchety. Maybe they learned something useful over all those years and all those lines of code.
Its for wussies!
-USe tons and tons of goto statements.
-Make sure you use particular letters capped for variables of different types to make them more confusing for the losers who can't read the code and remember what each one was.
- always make calls by reference using pointers as arguments. Don't use call by values.
- Hell user other pointers that use other pointers to make things more interesting. Reassign them all over the place
- Never use a three tier model when developing client/server apps. This only creates redundancy and gets in the way of solving the problem.
- When linking to a database always use vendor specific extensions and avoid a database layer using something like odbc. It makes use of the advanced feature set by the particular RDBMS.
- Be a man! Show how much you know perl. Alot of one linners can save tons of time with exotic line switches
Oh last... make tons of money and gain job security because no one in Earth will be able to understand or work on your projects after doing all of these things. Enjoy
http://saveie6.com/
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.
In addition to some of the suggestions made so far I would add a good automatic regression-test system which runs every night, and reports problems (build failures or result diffs). I've made mine so they "find the guilty" (whoever committed code since the last good regresstion test).
I recently put together a list of Fundamental Coding Truths after musing about this topic and why it was so hard to plan software development:
1. Software is not at its core a collection of a few clever algorithms.
Rather, it is primarily (in the ways that matter) a huge collection of arbitrary
choices and random implementation details.
The algorithms that consititute the mathematical/logical basis of a piece of software
are an important, but very small (eg: 1%) and relatively very simple part
of the overall code.
2. Code complexity is pretty much exclusively determined by the (combinatorial)
number of interactions between pieces. Each interaction requires at least one decision
and usually many more.
3. Because of #1 and #2, deep, intimate familiarity with the code (this vast
collection of implementation details) is only ever fully knowable to the original
author(s) who made these uncountably many, mostly arbitrary decisions.
(Familiarity by secondary authors/maintainers comes primarily from
re-writting sections of code.)
4. Because of #3, programmers are not interchangeable. The efficiency with
which a person can navigate the code, implement or even imagine changes
is almost entirely determined by how familiar they are with these many, many small
details. The ratio of efficiencies between a primary author and another
equally talented coder is very large (eg: 100). Because of this, the original
authors of a section of code are usually the only ones who are ever able to efficiently
modify or restructure it. This becomes rapidly more true as the the size and
complexity of the code increases.
5. Because of the complexity of code (the number of interactions and interdependencies),
debugging and maintenance constitutes the vast majority (eg: 99.9%) of the work
required by a piece of software over its life.
6. Because of the complexity of code (number of interactions between components), it is
very hard, if not impossible, to predict with any accuracy what will be involved in implementing
a given change. Even for original authors, unintented side effects are almost inevitable, and
the primary determinant of the length and difficulty of a task lies in finding and rectifying
unintented consequences or unforseen interactions. Because of this, the uncertainty in the time
it will take to execute a change is very large.
(eg: 10x range in 95% confidence limit of time estimate, say 1 day-2weeks).
7. Because of the complexity of code, bugs are an inevitable byproduct of writing code. It is hard
to predict how long it will take to find and repair bugs as that depends on how many side effects are
involved, which is not known until the repair is done and "fully tested". The only way to avoid bugs
completely is to not write code. There are things that can minimize bugs or speed up finding/fixing
them, but they will always exist.
Snowden and Manning are heroes.
Hungarian notation has its (extremely limited) uses. The reality is that it turns code into garbage. Go ahead, read aloud the lines of code below.
// the old c style
if(cur == last) rec->tag = name;
// camel case
if(currentKey == lastEntry) Record->keyTag = userName;
// hungarian
if(iCurrentKey == iLastEntry) prRecord->m_pszKeyTag = pszUserName;
Now imagine discussing them with your coworker. Imagine thinking in your head "What should I do if prRecord->m_pszKeyTag is NULL?" Humans are good at symbolic manipulation. Giving something a name makes it easier to deal with. Giving something a label that cannot be easily manipulated in language (spoken or in your head) severely hampers the ability to think it through.
The argument for Hungarian is usually "but it lets you know what the variables are". This is the maintainance programmer argument. This argument rarely makes sense in reality, unless some very bad programming is involved. First of all, if you do not understand the current code you are about to modify, you should *not* be modifying it. If your maintainance programmer is just going to have a look at two lines of code, add a third in the middle, and hope for the best then you are truly fucked. He has obviously not understood the code enough to know what the consequences of the modification will be. The reality is, if your current logic unit is such a monstrosity that looking up the types of your variables is a burden, and your variable names are so poor that it is insufficient to infer at least a basic understanding of what is going on without having to resort to prepending types, you should probably step away from the keyboard, turn off your computer, and tell your boss that you had an epiphany and will be pursuing a career in French fry development.