tips, guidelines, points to remember for rendering professional code?

Question

I'm talking about giving clients professional looking code. The whole nine yards, everything you hardcore professional highly experienced programmers here probably do when coding freelance or for the company you work in.

I'm fresh out of college and I'm going into freelance. I just want to be sure that my first few projects leave a good after-taste of professionalism imprinted on the clients' minds.

When I Googled what I'm asking here, I was given pages that showed various websites and tools that let you make flashy websites and templates etc. The $N package and such stuff.

I can't recall the word experts use for it. Standard, framework [I know that's not it]. English isn't my first language so I'm sorry I don't really don't know the exact phrase for it.

That abstract way of writing code so that you don't come across as a sloppy programmer.

That above mentioned way for programming websites and desktop software [in python/C/C++/Java].

EDIT: I can work on the accruing vast knowledge and know-how and logic building etc. what I'm asking for is the programming standard/guidelines you guys follow so that the client on seeing code feels that its a professional solution. Like comment blocks, a particular indentation style something like that. Is there any book on it or specific list of points for enterprise type coding by them? Especially here as in my case, for building websites [php for now..], and desktop software [c/c++/java/python]

Answer 1

• Consistency is king. Pick a naming/capitalization standard and stick with it. If you're confident, come up with your own, but it'll be much easier if you grab an already existing standard
• Comment your functions by explaining what they are trying to do. Not what each line of code does but more like "this function take in 2 numbers, multiplies them and returns the result"
• Group relevant functions together into well named classes - not as easy as it sounds
• Get your error logging happening at the start of the project and log DEBUG, INFO, WARN and ERROR logs
• Get your error handling framework happening at the start of the project so it's consistent
• Don't plaster your name all over your code or put in stupid comments in your code (like "// warning, this is a hack because Y sux"). Don't use obscenities or racial language etc. Sounds too obvious? You'd be surprised.
• Don't go overboard in your design!! Just because you want it to be professional doesn't mean it has to have 6 layers and a million classes. Keep it simple!
• Don't re-invent the wheel. Very common for young grads. Use libraries that have already done the work for you!
• If you're doing web stuff, separate out your CSS and Javascript to separate files. Keep your Javascript simple.
• Write Unit Tests - keep it simple though.
• If you're talking to a database, create a database project that abstracts away the DB stuff from your front-end.
• Use a source code revision management tool. Which one? Any of them, just use one.
• Keep code file sizes smallish. Opinions vary but I reckon anything over 1000 lines should be broken up into smaller files.
• Don't hardcode filesystem paths, server names or "magic numbers". Use relative paths, put server names into a config file and use constants.
• Use relative URLs.
• Catch as many errors at compile-time if possible. Makes cleaning up your code easier.
• Don't be afraid to refactor stuff.
• Don't "optimise" your code if it doesn't need to be optimised. Premature optimisation will make your code a mess. Don't do anything stupid like reading 10 gig of data into ram too.
• Only cache stuff if you need to. Keep it simple.

A few other non programmy things you're going to have to learn:

• How to estimate and project plan. People will ask you for an estimate, be prepared.
• Document the customers requirements. This will make things easier for you and them.
• Get someone (preferably experienced) to review your code after you've written a week or two's worth. It will only take them a few minutes to glance over it all to point out what will be obvious to them but not you.
• Learn about design patterns but don't overzealously use them for the sake of it.
• Backup your stuff.
• Keep track of bugs, issues and feature requests somehow (they are all different things). Just a text file is fine, but either way do it. Someone will eventually ask you for it.
• Keep up to date with frameworks/libraries so that you're not doing things a really old way that can be done quicker and easier with a new library. If it seems way to hard then there's probably (hopefully) a much easier way of doing things.
• If there's any complicated logic going on, document it somehow with a flowchart or just write it out in english. Don't expect that someone will spend 2 days trying to reverse engineer your code.

I'd also suggest that as you're just out of college you won't get things right the first time, nor the second time (none of us do). My advice would be to try to join a team of experienced developers, learn for them, and then a few years later consider freelancing. But hey if you want to get stuck into it good luck :)

Answer 2

Rather then form a belief about what it means to "be professional" I would recognize your clients particular beliefs and tailor yourself around them. The best way to find out what they want is to ask them. This is good advice in any relationship.

Readability and effective code often come hand in hand and both are part of having a better solution. I believe you might get better results learning what you can do to improve posting some of your solutions on code review and having people give specific advice.

Answer 3

what i'm asking for is the programming standard/guidelines you guys follow so that the client on seeing code feels that its a professional solution

1. From client and project perspective - asking questions, clarifying client needs, following pre-existing application standards(if you are supporting and enhancing an existing application), documenting your code, and improving all these steps as needed.

2. For professional development - this sounds to me as a need to keep learning, using, practicing and mastering your SOLID Principles. The way to go for building ROCK SOLID applications.

NOTE: However, it really make difference on what type of applications are you working on. My advice is for enterprise level, high performing, scaleable application development.

We all heart about the coding standards like KISS and YAGNI . They are easy to remember and follow, as far as we are trying to improve yourselves. Thus, it is a constantly revolving process to follow.

References:

• Best Coding Practices - wiki
• Development best practices: coding standards and the “20 lines” rule
• Front-end Code Standards & Best Practices
• Java Best Practices, Code Conventions and Style Guide
• Coding Standards & Best Practices - Omaxy source

Answer 4

The most basic technique gives the most bang for the buck. Single purpose modules. It might seem a little too obvious and basic but single purpose modules gives you good code. It's half the battle.

The modules could come in the form of functions, classes, separate projects compiled to DLL, a source-code level macro, etc.

Separate things out till they are single purpose, then they can be reused.

Answer 5

Read Code Complete by Steve McConnell. Apply it's principles on every line of code, literally.

My best "ah-ha" moments in coding excellence have been when I reworked particularly bad code and had a striking before and after picture, so to speak.

You will learn that applying coding principles is a synergistic balancing act, that the most trivial guidelines matter, and that code crumbles one poor, lazy edit at a time.

Answer 6

If you want to give your codebase a "professional" look, a good idea is to make it follow a particular set of published guidelines/conventions/standards. For example, a Java-based project might follow Oracle's Java Code Conventions. Use an IDE that has an automated code style formatter (e.g. Eclipse) to ensure no code ever gets committed that does not follow the chosen style of the project.

Answer 7

You might consider reading a book like "The Art of Readable Code", by Dustin Boswell and Trevor Foucher.

Also, when you learn a new programming language, do not invent you own style. Follow the established style (identifier naming: underscores, camelCase; indentation, etc.) used by more experienced people. Above all, be consistent.

Have your line comments answer the questions "Why?" and "How?", not so much "What?". For example, if you use an unusual algorithm, cite its wikipedia page. If you traverse an array from last to first instead of from first to last, explain your reason. You will thank yourself 6 months later when you read your own code.

Use well-established programming patterns like those listed in "Design Patterns", by the "Gang of Four", and, in complicated cases, cite which pattern(s) you use.