| 87 | | === adding documentation to existing code === |
| 88 | | |
| 89 | | Another useful habit to get into is to add documentation to existing code on the go where its missing to clarify whats happening. The MapGuide code base has been a commercial product before for many years, so its not a surprise that the new documentation standards have not been always followed. |
| 90 | | If you spend half an hour figuring out what happened in a code section you are calling or which has called your code, add some helpful comments there too as it will help you and others next time trying to understand it. |
| 91 | | |
| 92 | | Its a good idea to submit patches for files you were only adding inline documentation to as its not so likely that the original developer will need comments to understand it and do this for you. |
| 93 | | |
| 94 | | === Copy and Paste vs. method extraction === |
| 95 | | |
| 96 | | Many times copy and paste seems a quick way to make code work. But it also inflates the code and there is a risk of obfuscating essential details. If some code is doing the same thing try to extract a helper method and reuse this method. This makes code much easier to read and understand. In the extreme case copy 'n paste leads us to hundreds of lines of identical code with just a few lines of changes inside. This is doomed to cause defects when anything changes later in time as the code has to be changed in many places instead of one. |
| | 87 | === Adding Documentation to Existing Code === |
| | 88 | |
| | 89 | Another useful habit to get into is to add documentation to existing code on the go where it's missing or needs enhancing. If you spend half an hour figuring out what happened in a code section you are calling or which has called your code, add some helpful comments as it will help you and others next time trying to understand it. |
| | 90 | |
| | 91 | It's also worthwhile to submit patches for files you were only adding inline documentation to, as it's less likely that the original developer(s) will need comments to understand the code and do this for you. |
| | 92 | |
| | 93 | === Copy and Paste vs. Method Extraction === |
| | 94 | |
| | 95 | Many times copy and paste is an easy way to make code work. The downside is that it inflates the code and there is a risk of obfuscating essential details. If some code is doing the same thing it's worthwhile trying to extract a helper method so that it can be reused. This makes the code much easier to read and understand. In the extreme case copy 'n paste leads to hundreds of lines of identical code with just a few lines of changes inside. This significantly increases the risk of introducing defects, since when anything changes later in time the code has to be changed in many places instead of one. |
