|
| 1 | +tags:: Software Development |
| 2 | +topic:: [[Programming Concepts]] |
| 3 | +softdev:: Unit 3 Outcome 1 |
| 4 | + |
| 5 | +- |
| 6 | +- the notes and comments written by a programmer within the code itself |
| 7 | +- includes information about the program as a whole, including |
| 8 | + - about each of the classes, methods, objects, algorithms, etc. within it |
| 9 | + - combined with using a [[Naming Convention]] to include well-named variables to create understandable and maintainable code |
| 10 | +- has no impact on the compilation or running of the code |
| 11 | + - extensive documentation may increase storage size for source code, but is usually negligable |
| 12 | +- exists only to provide context and important information about the code |
| 13 | +- most useful when a programmer is reading through code that they did not write themselves, or that was written in the past |
| 14 | + - relying on memory alone or on interpreting complex algorithms to understand what code is doing is hard work |
| 15 | +- saves time |
| 16 | + - reduces developer effort |
| 17 | + - more efficiently creating and maintaining software |
| 18 | +- good Internal Documentation practices |
| 19 | + - write meaningful internal documentation for your code |
| 20 | + - help you and other developers understand how the code works |
| 21 | + - include |
| 22 | + - file header comments |
| 23 | + - documentation of classes and methods |
| 24 | + - function and subroutine comments |
| 25 | + - single-line and multi-line comments explaining why code is written this way such as |
| 26 | + - to work with another system |
| 27 | + - legal requirement constraint |
| 28 | + - things that aren't immediately obvious just by looking at the code (background) |
| 29 | + - information about testing |
| 30 | + - possibly add extra information on upgrades, changes or enhancements made |
| 31 | + - [[Version Control]] will also house documentation related to code change |
| 32 | + - clear and concise |
| 33 | + - avoid jargon or technical terms that are not specific to the software domain |
| 34 | + - be specific |
| 35 | + - explain less about what code does and more about why it was written this way |
| 36 | + - be consistent |
| 37 | + - use the same style and format for your internal documentation throughout your code |
| 38 | + - follow standard documentation conventions for the programming language |
| 39 | + - keep it up to date |
| 40 | + - if the code changes, the documentation must be checked and updated as well, if needed |
| 41 | + - |
| 42 | + - |
0 commit comments