11/6/09 03:54 am - Haxor's guide to perfect code
I'm trying to learn how to write readable and maintainable code for some time (but often have to deal with very broken one) and here is what I want to highlight for everybody whose code I might be reading in future.
Most of the people think that programming is a process where you sit in front of computer and type the code. For a most of the cases this is not true. There are sure situations when you sit and write, but most of the time, you need to think first. So the work starts a little bit earlier, usually when you are walking in the park, cooking dinner or taking a shower. When you are sitting in front of the computer you should at least have a general idea.
Do not create overcomplicated solutions. There are more and less complex problems to be solved, complex problems calls for complex solutions but still they should be clear and understandable. Make the code as simple as possible but not simpler.
Be consistent. The code you write should be consistent, especially when you are creating library interface. There is nothing more confusing that library with inconsistent interface. When you start using same naming convention, use it in whole project. For example when one data structure has method Delete, similar ones should name it same way.
Break complicated things into small parts. It's a good practice to build complicated functionality from small parts with well defined functionality. This is called encapsulation. This way you could think of parts of a code as they are black boxes that does something and the good part is that you don't need to focus on how it's done. However sometimes it's hard to find optimal cuts. In General you should optimize cuts so that your functions are not too long and have small number of parameters. Individual test for every black box is also good idea.
Avoid meaningless comments in code. Commenting code is good habit indeed but don't get overexcited, don't forget that you are writing code not poem. Also quite number of comments comes from silly named functions/variables. It's always better to name variable as iter_cnt instead of naming it g with comment /* this variable holds number of backwards iterations */. But beware names like my_little_iteration_counter, stay descriptive and short.
Found a dead end? Sometimes programmer finds out, in the middle of writing code, that one of the assumptions made on start is not correct anymore or wasn't correct at all, in that case don't be afraid to use delete key. But beware that delete is a powerful servant but a bad master.
When speed is not critical it's sometimes better to optimize for code readability and shortness than for speed. Typical example are initialization runtines that are called once at the start they could be a little bit slower, but on the other hand you should never write code that is way too slow if there is possibility to write it fast enough.
Okay that's all for today. May be more to come in the future.
Most of the people think that programming is a process where you sit in front of computer and type the code. For a most of the cases this is not true. There are sure situations when you sit and write, but most of the time, you need to think first. So the work starts a little bit earlier, usually when you are walking in the park, cooking dinner or taking a shower. When you are sitting in front of the computer you should at least have a general idea.
Do not create overcomplicated solutions. There are more and less complex problems to be solved, complex problems calls for complex solutions but still they should be clear and understandable. Make the code as simple as possible but not simpler.
Be consistent. The code you write should be consistent, especially when you are creating library interface. There is nothing more confusing that library with inconsistent interface. When you start using same naming convention, use it in whole project. For example when one data structure has method Delete, similar ones should name it same way.
Break complicated things into small parts. It's a good practice to build complicated functionality from small parts with well defined functionality. This is called encapsulation. This way you could think of parts of a code as they are black boxes that does something and the good part is that you don't need to focus on how it's done. However sometimes it's hard to find optimal cuts. In General you should optimize cuts so that your functions are not too long and have small number of parameters. Individual test for every black box is also good idea.
Avoid meaningless comments in code. Commenting code is good habit indeed but don't get overexcited, don't forget that you are writing code not poem. Also quite number of comments comes from silly named functions/variables. It's always better to name variable as iter_cnt instead of naming it g with comment /* this variable holds number of backwards iterations */. But beware names like my_little_iteration_counter, stay descriptive and short.
Found a dead end? Sometimes programmer finds out, in the middle of writing code, that one of the assumptions made on start is not correct anymore or wasn't correct at all, in that case don't be afraid to use delete key. But beware that delete is a powerful servant but a bad master.
When speed is not critical it's sometimes better to optimize for code readability and shortness than for speed. Typical example are initialization runtines that are called once at the start they could be a little bit slower, but on the other hand you should never write code that is way too slow if there is possibility to write it fast enough.
Okay that's all for today. May be more to come in the future.
