Don't be a jerk, organize your code.
This is a rant every developer either needs to hear, or needs to share.
Today I was inspired to say the following: I cannot count the times I have been introduced to a new application, and have nearly torn my hair out because of how badly it was fitted together. I mean for-pete-sake, some of you could at least pretend that another human being was going to see what you have written!
What I am getting at here is: organize, detail, and document your code.
Is it hard? No.
Does it take more time? Not with practice and consistency.
Will people like it? Yes.
STEP 1: Organize
Most developers don't have a problem with this one, but most do have some areas that could use some improvement. The first problem area is using spaces VS tabs. In short follow/create the projects style guide. (see @Paprikkastudio's comment below)
Some more common ones are file-naming-systems and file-layout. If you load a bunch of classes in PHP, separate each class into files like thisThing.class.php and thatThing.class.php; or if you have an extensive CSS file, consider adding a "table of contents" to the top.
Little extras like these, are extremely helpful for others trying to browse your code. Additionally, it can really benefit you as well, if you need to find something quickly.
From here, it spans almost into common sense. If your code looks similar to a crossword puzzle, consider revising it. If you have a comment block, try not to let a line exceed ~100 characters (for those of us not blessed with the gift of 'word-wrap'). So on, and so forth.
STEP 2: Detail
This is where your comment blocks/lines are the most helpful. Anytime the code gets a little confusing, or uses some weird thing not even mentioned anywhere else in the file, add a comment. Tell us what the heck is going on here.
When something gets confusing, a little hint can help. Inserting a quick # thisVar is now = thatVar, or something like that, can help clear things up.
When it comes to random things that aren't mentioned often... While I just love spending 3 hours looking through files just find out $someVariable created by thisFunction is boolean, I won't want to stab you with a rusty spoon if you just write the following:
// $thisVariable (bool) is created by thisFunction() in /this/path/here.php
Many people prefer to use PHPDoc (or similar systems), as a substitute. In general, I think this acceptable, but additional code hinting as needed is still recommended.
STEP 3: Document
While I could go on forever about this, just document your code. Make it so that someone can read and understand what you code basically does. And while you're at it, use a versioning system that makes sense.
Your users/devs will love you, you'll save time, you will make more money.... Just do it.
Thanks for reading
If you enjoyed what I wrote, consider upvoting this protip or endorsing me.
If you want to see more of my stuff, you can see other protips I have written or visit my profile.
Written by Nicholas Jordon
Related protips
9 Responses
"The first area is one I have personally been guilty of in the past: using spaces rather than tabs."
I guess it's better to use spaces, because if you work in a team, you don't need to get used the new indenting style if the developer uses different tab sizes, so easier to read the code on other people's screen. It's a personal opinion.
@nucc While I understand what your saying, in my opinion what you said is just silly. More or less for the following reasons:
How much it effects my programming ability to read different tab sizes: 0.0%
How much I appreciate it when programmers consider other people: 100.0%
Coincidentally, this entire article is about reason number two.
@projectcleverweb I use spaces, because I do consider other people. On the other hand, this is so annoying (and still looks even worse in my IDE)
Nevertheless, great post, I agree with you in 100% (minus indentation :) ). I've spent the last year and half trying to organize the way both front- and back-end development teams in my previous company created web apps, despite the fact that I was responsible only for front-end dev / designers. And I have to say I'd be the happiest man on this planet if indentation would have been our biggest issue :)
I still don't understand how in the year 2013 there are devs who haven't heard of: git / mercurial / svn / any other versioning system. This crime should be punished with forcing them to use Adobe Version Cue for at least one year.
- CamelCase and snake_case in the same app are not the nicest gift you could give your teammate (ie. 10-page long style guide on your desk is there for a purpose)
If I may put my two cents in:
- please, remember that: someday, someone will read your code
- develop a styleguide (or use existing one)
- create a wiki for your project (it's easy because you're using github / bitbucket, aren't you?)
- document your API
- this one is particularly for JS devs: lint your code
- believe me or not, writing readable code is easy. People are afraid of change, some are just plain lazy, but in most cases those who write really messy code are somehow convinced that organization needs a lot of additional time, which is not true after one or two weeks. My personal definition of developer's job would be: it's creating solutions for problems in the most efficient, simple and organized way, providing structure and mechanisms that work and evolve. As Linus Torvalds said:
"If you need more than 3 levels of indentation, you're screwed anyway, and should fix your program."
By the way, this quote appeared in a linux styleguide.
@paprikkastudio Great points, I hadn't thought to mention style guides. I'll add a mention to your comment in the article. @nucc The reason I like his comment and not yours is he gave valid and detailed reasons. Though due to the length, I may have suggested he write it as an article; but in any case, thank you both for your comments.
You can never attribute for the level of skill of the next person to read your code either, that means comment (where sensible) for a fairly low level. This will allow junior devs to learn from/read your code and allow high-level devs to skim-read your comments until you throw in something complex, whereby they read your comments and understand what you've done (be it right or wrong).
Readable code means more easily extensible code, for you in 3 months time or for another dev, this is a good thing. Compared to proper documentation (which is also good) readable code is easy so there are simply no excuses, even if you are pre-disposed to writing over-complex spaghetti-code, a good piece of commenting will do wonders for the next chap.
Comments are easily removed during the build process anyway but needn't be a chore, like writing tests, writing comments first and then implementing can help even the most advanced to write good code.
This is great, except for the blurb on PHP class file naming conventions. When it comes to naming PHP class files, the file names and directory hierarchy should follow the PSR-0 standard[1]. Why? Its a standard, its widely adopted, it actually makes sense, and it let's you stop worrying about making those decisions yourself (and lets you just worry about coding). ;)
As far as code style and indentation go for PHP, its highly suggested that developers follow the PSR-2 standard[2]... even if its a little different than what people are used to, for the same reasons above as using PSR-0.
[1] https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
[2] https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md
I think the book Clean Code by Robert Martin should be included as a compulsory subject in every programming course syllabus...
Being consistent with naming conventions and files structure also helps a lot and is frequently overlooked!
You presume that when folks walk into an integration situation that there's a well thought out style guide to begin with. I assure, in my experience, that is most certainly NOT always the case. And convincing people to take the time to impose one is fighting a loosing battle.
