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
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.