Treat your code as documentation

Your code is your primary documentation. It precisely describes what the resultant app, library or whatever, actually does. As such, any attempts at speed up the understanding of that code has to start with the code itself.

There's lots written on how to write readable code, but some of the key points are:

• do not rely on comments to explain bad code, make the code better and get rid of the comments,
• write short focused functions, methods, classes etc,
• use names appropriate to the context (eg n is good for a loop, longer descriptive names are needed for items with greater scope),
• treat function names as if they were comments, eg don't use UpdtTbl with a comment explaining it updates the table with the supplied rules when UpdateTableContentsWithSuppliedRules can be used as the name,
• avoid mutability. Every time you change the contents of a variable, you increase the complexity of the code. Assign that new value to a new variable (with a good name) where feasible.
• lastly, and most importantly, avoid "clever" code. The only real clever code is code that is easy to read. If you write some complex bit of code and find yourself think "wow, aren't I clever here?", the answer is almost guaranteed to be "no, you aren't".

Reading code, regardless of how simple it is, is a learned skill. No one is naturally good at reading code. It takes practice; lots of practice. So, for example, go to Github or whatever and read the code of the libraries that you use, rather than just using those libraries. Find code to read and read it.

Comments are a code smell

Only then do we get to other types of documentation. Firstly, as previously stated, avoid comments. If I come across code containing comments, I prepare for the worst: the code is likely to be bad, and to be honest the comments are likely to be bad too. Someone who can't communicate well through code is unlikely to be able to communicate any better through natural language.

** Beware autogenerated API documentation**

Also, beware autogenerated API documentation. If I have to resort to reading such docs, it'll be because your code is so hard to read. Again, make the code simple and I can read that directly.

Tests are docs, too

Tests are documentation too. So don't treat your unit tests as a chore. Treat them as a way of communicating with others (your six month's later self being included here) as to how the code works and is intended to be used.

Draw pictures if it helps

If you like UML, then by all means find yourself a good tool and generate UML diagrams from your code. Just never ever ever ever try to use it to generate code. It's not good as a design tool and you will end up with horrible code as a result.

Have a "1000ft" view document

Finally, write yourself an overview document. What does the app do? How does it do it? What other systems does it connect to? Things like that. Do not attempt to describe the code structure here though. Let the code do that. Let this document remind you why you wrote the code in the first place.

Treat your code as documentation

Your code is your primary documentation. It precisely describes what the resultant app, library or whatever, actually does. As such, any attempts at speed up the understanding of that code has to start with the code itself.

There's lots written on how to write readable code, but some of the key points are:

• do not rely on comments to explain bad code, make the code better and get rid of the comments,
• write short focused functions, methods, classes etc,
• use names appropriate to the context (eg n is good for a loop, longer descriptive names are needed for items with greater scope),
• treat function names as if they were comments, eg don't use UpdtTbl with a comment explaining it updates the table with the supplied rules when UpdateTableContentsWithSuppliedRules can be used as the name,
• avoid mutability. Every time you change the contents of a variable, you increase the complexity of the code. Assign that new value to a new variable (with a good name) where feasible.
• lastly, and most importantly, avoid "clever" code. The only real clever code is code that is easy to read. If you write some complex bit of code and find yourself think "wow, aren't I clever here?", the answer is almost guaranteed to be "no, you aren't".

Become better at reading code

Reading code, regardless of how simple it is, is a learned skill. No one is naturally good at reading code. It takes practice; lots of practice. So, for example, go to Github or whatever and read the code of the libraries that you use, rather than just using those libraries. Find code to read and read it.

Comments are a code smell

Only then do we get to other types of documentation. Firstly, as previously stated, avoid comments. If I come across code containing comments, I prepare for the worst: the code is likely to be bad, and to be honest the comments are likely to be bad too. Someone who can't communicate well through code is unlikely to be able to communicate any better through natural language.

Beware autogenerated API documentation

Also, beware autogenerated API documentation. If I have to resort to reading such docs, it'll be because your code is so hard to read. Again, make the code simple and I can read that directly.

Tests are docs, too

Tests are documentation too. So don't treat your unit tests as a chore. Treat them as a way of communicating with others (your six month's later self being included here) as to how the code works and is intended to be used.

Draw pictures if it helps

If you like UML, then by all means find yourself a good tool and generate UML diagrams from your code. Just never ever ever ever try to use it to generate code. It's not good as a design tool and you will end up with horrible code as a result.

Have a "1000ft" view document

Finally, write yourself an overview document. What does the app do? How does it do it? What other systems does it connect to? Things like that. Do not attempt to describe the code structure here though. Let the code do that. Let this document remind you why you wrote the code in the first place.

Your code is your primary documentation. It precisely describes what the resultant app, library or whatever, actually does. As such, any attempts at speed up the understanding of that code has to start with the code itself.

There's lots written on how to write readable code, but some of the key points are:

• do not rely on comments to explain bad code, make the code better and get rid of the comments,
• write short focused functions, methods, classes etc,
• use names appropriate to the context (eg n is good for a loop, longer descriptive names are needed for items with greater scope),
• treat function names as if they were comments, eg don't use UpdtTbl with a comment explaining it updates the table with the supplied rules when UpdateTableContentsWithSuppliedRules can be used as the name,
• avoid mutability. Every time you change the contents of a variable, you increase the complexity of the code. Assign that new value to a new variable (with a good name) where feasible.
• lastly, and most importantly, avoid "clever" code. The only real clever code is code that is easy to read. If you write some complex bit of code and find yourself think "wow, aren't I clever here", the answer is almost guaranteed to be "no, you aren't".

Reading code, regardless of how complex it is, is a learned skill. No one is naturally good at reading code. It takes practice; lots of practice. So, for example, go to Github or whatever and read the code of the libraries that you use, rather than just using those libraries. Find code to read and read it.

Only then do we get to other types of documentation. Firstly, as previously stated, avoid comments. If I come across code containing comments, I prepare for the worst: the code is likely to be bad, and to be honest the comments are likely to be bad too. Someone who can't communicate well through code is unlikely to be able to communicate any better through natural language.

Also, beware autogenerated API documentation. If I have to resort to reading such docs, it'll be because your code is so hard to read. Again, make the code simple and I can read that directly.

Tests are documentation too. So don't treat your unit tests as a chore. Treat them as a way of communicating with others (your six month's later self being included here) as to how the code works and is intended to be used.

If you like UML, then by all means find yourself a good tool and generate UML diagrams from your code. Just never ever ever ever try to use it to generate code. It's not good as a design tool and you will end up with horrible code as a result.

Finally, write yourself an overview document. What does the app do? How does it do it? What other systems does it connect to? Things like that. Do not attempt to describe the code structure here though. Let the code do that. Let this document remind you why you wrote the code in the first place.

Treat your code as documentation

Your code is your primary documentation. It precisely describes what the resultant app, library or whatever, actually does. As such, any attempts at speed up the understanding of that code has to start with the code itself.

There's lots written on how to write readable code, but some of the key points are:

• do not rely on comments to explain bad code, make the code better and get rid of the comments,
• write short focused functions, methods, classes etc,
• use names appropriate to the context (eg n is good for a loop, longer descriptive names are needed for items with greater scope),
• treat function names as if they were comments, eg don't use UpdtTbl with a comment explaining it updates the table with the supplied rules when UpdateTableContentsWithSuppliedRules can be used as the name,
• avoid mutability. Every time you change the contents of a variable, you increase the complexity of the code. Assign that new value to a new variable (with a good name) where feasible.
• lastly, and most importantly, avoid "clever" code. The only real clever code is code that is easy to read. If you write some complex bit of code and find yourself think "wow, aren't I clever here?", the answer is almost guaranteed to be "no, you aren't".

Reading code, regardless of how simple it is, is a learned skill. No one is naturally good at reading code. It takes practice; lots of practice. So, for example, go to Github or whatever and read the code of the libraries that you use, rather than just using those libraries. Find code to read and read it.

Comments are a code smell

Only then do we get to other types of documentation. Firstly, as previously stated, avoid comments. If I come across code containing comments, I prepare for the worst: the code is likely to be bad, and to be honest the comments are likely to be bad too. Someone who can't communicate well through code is unlikely to be able to communicate any better through natural language.

** Beware autogenerated API documentation**

Also, beware autogenerated API documentation. If I have to resort to reading such docs, it'll be because your code is so hard to read. Again, make the code simple and I can read that directly.

Tests are docs, too

Tests are documentation too. So don't treat your unit tests as a chore. Treat them as a way of communicating with others (your six month's later self being included here) as to how the code works and is intended to be used.

Draw pictures if it helps

If you like UML, then by all means find yourself a good tool and generate UML diagrams from your code. Just never ever ever ever try to use it to generate code. It's not good as a design tool and you will end up with horrible code as a result.

Have a "1000ft" view document

Finally, write yourself an overview document. What does the app do? How does it do it? What other systems does it connect to? Things like that. Do not attempt to describe the code structure here though. Let the code do that. Let this document remind you why you wrote the code in the first place.