Please enable JavaScript.
Coggle requires JavaScript to display documents.
writing a document - Coggle Diagram
writing a document
-
Interface documentation
code is not good at present abstraction, so if you want to presents good abstractions, you must document those abstractions with comments
separate interface commends and implementation commends: if an interface comment must also describe the implementation, then the class or method is shallow
- start with a sentence or two describing the behavior of the method as perceived by callers; -- high level
- the comment must describe each argument and the return value (if any). These comments must be very precise, and must describe any constraints on argument values as well as dependencies between arguments
- If the method has any side effects, these must be documented in the interface comment. A side effect is any consequence of the method that affects the future behavior of the system but is not part of the result. For example, adds value to internal data structure, write to file system.
- must describe any exceptions that can emanate from the method.
- any preconditions that must be satisfied before a method is invoked (a must be invoked before b, in binary search, the input must be sorted)
-
for
the process of writing comments, if done correctly, will actually improve a system's design.
Conversly, a good software design loses much of its value if it is poorly documented.
the overall idea of write good comments is to capture information that was in the mind of the designer but could't be represented in the code.
someone who come along later to make modifition, will work more quickly and accurately.
without the comment, one need to re-derive or guess -- lead to more time and bugs
complexity
-
cognitive load: in order to make a change, the developer must accumulate a large amount of information.
unknown unkonwns: it's unclear that what code needs to be modified, or what infromation must be considered in order to make those changes
against
even in teams encourage documentation, this if often viewed as drudge work
don't know how wirte them, so the resuilt is often mediocre
-
Conclusion
The goal of comments is to ensure that the structure and behaviour of the system is obvious to readers, so they can quickly find the information they need and make modifications to the system with confidence that they will work. Some of this information can be represented in the code in a way that will already be obvious to readers, but there is a significant amount of information that can't easily be deduced from the code. Comments fill in this information.
-
if your code review comments that something is not obvious, don't argue with them; if a reader thinks it's not obvious, it's not obvious. Instead of arguing, try to understand what they found confusing and ses if you can clarify that, either with better comments or better code.
-
-