More on this book
Community
Kindle Notes & Highlights
Documentation can also reduce the unknown unknowns by clarifying the structure of the system, so that it is clear what information and code is relevant for any given change.
This here is a good point; need to consider writing documentation regarding dependent methods..
The reason for writing comments is that statements in a programming language can’t capture all of the important information that was in the mind of the developer when the code was written.
This is a very good point!!
Sometimes it’s not clear why code is needed, or why it was implemented in a particular way. Sometimes there are rules the developer followed, such as “always invoke a before b.” You might be able to guess at a rule by looking at all of the code, but this is painful and error-prone; a comment can make the rule explicit and clear.
Othmar made the same clear suggestions sometime ago.
requirements the caller must satisfy before invoking the method.
This is a good point; especially when considering code written for a general object as input that may have a certain assumption regarding the state of that object.
Cross-module comment: a comment describing dependencies that cross module boundaries.
This last point on comment type is very important; since could easily lead to confusion when a certain module is assumed.
When documenting a variable, think nouns, not verbs. In other words, focus on what the variable represents, not how it is manipulated.
Code itself will document the manipulation.
They omit details and help the reader to understand the overall intent and structure of the code.
In reference to 'higher level comments that enhance code intuition'. Think one of the best ways to do this is to have a text file which explains the code at an extremely high and abstract level for the whole project; simply detail the script, its function, how it relates to other scripts, and a high level description of the goal of the code.
Engineers tend to be very detail-oriented. We love details and are good at managing lots of them; this is essential for being a good engineer. But, great software designers can also step back from the details and think about a system at a higher level. This means deciding which aspects of the system are most important,
In other words, need the capacity for conceptual explanation.
This is the essence of abstraction (finding a simple way to think about a complex entity), and it’s also what you must do when writing higher-level comments. A good higher-level comment expresses one or a few simple ideas that provide a conceptual framework,
In other words, your higher level comments should explain the image you held within your mind when writing the code in order to recreate that image in the mind of the person attempting to understand it; thus granting the capacity for the person to look at the code with the eyes of the person who created it.
The first step in documenting abstractions is to separate interface comments from implementation comments.
Interesting idea.
Red Flag: Implementation Documentation Contaminates Interface This red flag occurs when interface documentation, such as that for a method, describes implementation details that aren’t needed in order to use the thing being documented.
The biggest challenge with cross-module documentation is finding a place to put it where it will naturally be discovered by developers.
I think a general notes.txt is a good place to define this within the project.
I have recently been experimenting with an approach where cross-module issues are documented in a central file called designNotes.
Hey this is what i do!!
in any piece of code that relates to one of these issues there is a short comment referring to the designNotes file: // See "Zombies" in designNotes.
This is a great idea, hand't thought of adding comments which link from the code to the relevant section of notes.txt!
When writing comments, try to put yourself in the mindset of the reader and ask yourself what are the key things he or she will need to know.
The good old' adam smith imagination trick :)
If your code is undergoing review and a reviewer tells you that something is not obvious, don’t argue with them; if a reader thinks it’s not obvious, then it’s not obvious. Instead of arguing, try to understand what they found confusing and see if you can clarify that, either with better comments or better code.
This is true of any form of communication!! This is great.
Create an image When choosing a name, the goal is to create an image in the mind of the reader about the nature of the thing being named.
As is the goal of everything here when you are programming; define the programming abstraction in a way extremely clear so the reader can vividly imagine it.
The term “count” is too generic: count of what? If someone sees an invocation of this method, they are unlikely to know what it does unless they read its documentation. A more precise name like getActiveIndexlets or numIndexlets
Red Flag: Vague Name If a variable or method name is broad enough to refer to many different things, then it doesn’t convey much information to the developer and the underlying entity is more likely to be misused.
you find it difficult to come up with a name for a particular variable that is precise, intuitive, and not too long, this is a red flag. It suggests that the variable may not have a clear definition or purpose.
I like this idea, if you can't name it, variable might not be a good abstraction.
Red Flag: Hard to Pick Name If it’s hard to find a simple name for a variable or method that creates a clear image of the underlying object, that’s a hint that the underlying object may not have a clean design.
Use names consistently The second important property of good names is consistency. In any program there are certain variables that are used over and over again.
This would mean across the whole application; i have definitely been guilty of not using consistent names between modules - need to correct this.
Consistency has three requirements: first, always use the common name for the given purpose; second, never use the common name for anything other than the given purpose; third, make sure that the purpose is narrow enough that all variables with the name have the same behavior.
Great advice.
Overall, I would argue that readability must be determined by readers, not writers. If you write code with short variable names and the people who read it find it easy to understand, then that’s fine. If you start getting complaints that your code is cryptic, then you should consider using longer names
I always aim to make my code read as close to english as possible.
Gerrand makes one comment that I agree with: “The greater the distance between a name’s declaration and its uses, the longer the name should be.”
Or, the more detailed the name should be. I disagree; goal should be to make the code read as close to english as possible, this is what makes the python syntax so popular. Good chance anyone reading your code already speaks english, afterall.
Not only does this produce better documentation, but it also produces better designs and it makes the process of writing documentation more enjoyable.
Feynman says the best way to test your understanding, is to explain to someone else. This can also be in the context of writing; but i think in general that this is useful for any kind of expression.
Even if you do have the self-discipline to go back and write the comments (and don’t fool yourself: you probably don’t), the comments won’t be very good. By this time in the process, you have checked out mentally. In your mind, this piece of code is done; you are eager to move on to your next project.
This is exactly what i am like with my research projects; thus i should be writing the manuscript constantly as i'm doing the project, and submit it when i'm done.. Using latex is probably best way for this; since then any figures i make along the way i can easily just import into my document without much effort. Thus gives a 'written version' of the code / outcomes from running the code.
i'm also guilty of this when writing code tests :s. So again, this should be done as i go.
15.3 Comments are a design tool The second, and most important, benefit of writing the comments at the beginning is that it improves the system design.
Agreed, writing comments like this has made me often think of better ways for writing the abstraction.
Comments serve as a canary in the coal mine of complexity.
The third and final benefit of writing comments early is that it makes comment-writing more fun. For me, one of the most enjoyable parts of programming is the early design phase for a new class, where I’m fleshing out the abstractions and structure for the class.
I share this sentiment :). This is the creative and most imaginative part, afterall.
In contrast, if you write the code first, the abstractions will probably evolve as you code, which will require more code revisions than the comments-first approach.
Exactly, it is much better to develop your mental image more clearly than trying to code blindly. The mental model is the most important aspect of solving any problem.
A large software system develops through a series of evolutionary stages, where each stage adds new capabilities and modifies existing modules. This means that a system’s design is constantly evolving.
Thus we should always setup our code and our projects for evolvability.
Unfortunately, when developers go into existing code to make changes such as bug fixes or new features, they don’t usually think strategically. A typical mindset is “what is the smallest possible change I can make that does what I need?”
Too short sighted of course. Beter question is "how can i set this up to minimise work in the future?"
Ideally, when you have finished with each change, the system will have the structure it would have had if you had designed it from the start with that change in mind.
This is a great philosophy to prevent complexity accumulation.
This is also an example of the investment mindset introduced on page 15: if you invest a little extra time to refactor and improve the system design, you’ll end up with a cleaner system.
Clean system = happy developer
If you’re not making the design better, you are probably making it worse.
“Is this the best I can possibly do to create a clean system design, given my current constraints?”
Every development organization should plan to spend a small fraction of its total effort on cleanup and refactoring; this work will pay for itself over the long run.
Absolutely; makes me worry about the lack of software skill amongst bioinformaticians.
The best way to ensure that comments get updated is to position them close to the code they describe,
The farther a comment is from its associated code, the less likely it is that it will be updated properly.
In general, the farther a comment is from the code it describes, the more abstract it should be (this reduces the likelihood that the comment will be invalidated by code changes).
If information is already documented someplace outside your program, don’t repeat the documentation inside the program; just reference the external documentation.
Good idea; this is meta level design decisions.
There are already numerous sources for this documentation on the Web; just add a short comment to your code with a URL for one of these sources.
Exactly, thus there should be articles called 'awareness' articles which simply include useful resource descriptions.
It’s important that readers can easily find all the documentation needed to understand your code, but that doesn’t mean you have to write all of that documentation.
Should refer to third party documentation too, such as scikit learn.
comments are easier to maintain if they are higher-level and more abstract than the code.
Consistency creates cognitive leverage: once you have learned how something is done in one place, you can use that knowledge to immediately understand other places that use the same approach.
This is also true of learning in general; need to find a low-dimensional understanding of the world so one can reason from some basic premises in order to generate a model of the world.
Consistency is hard to maintain, especially when many people work on a project over a long time.
Hence the danger of software like Seurat and Scanpy.
Document. Create a document that lists the most important overall conventions, such as coding style guidelines.
Could be useful in 'designNotes.txt'
“When in Rome, do as the Romans do.” When working in a new file, look around to see how the existing code is structured.
And refactor if it sucks; conform if is good
Don’t change existing conventions. Resist the urge to “improve” on existing conventions. Having a “better idea” is not a sufficient excuse to introduce inconsistencies. Your new idea may indeed be better, but the value of consistency over inconsistency is almost always greater than the value of one approach over another.
Disagree. If it is enough better, you should refactor. The current code might be written in an overly complex way,for instance.
