Humans And The Compiler: A Taxonomy Of Comments

taxonomy What kind of lemon juice to use?

Like can you put a pealed lemon in a blender and use straight up lemon juice?

Buy the kind of lemon juice thats in container that looks in a shape of a lemon? The human reader, moreover, will like to be able to remember the purpose of a code block, function, or package without reading its implementation.

Different audiences care about different levels of detail, and at different times.

Someone working on the implementation of a method needs a highlevel understanding of its implementation or algorithms as a roadmap of the implementation, maybe an overview of what every block does, but a ‘line by line’ understanding of a particular block within the method at only a particular time, a API user needs a description of a method’s external behavior.

taxonomy Comments let the reader turn the dial to positions betweeen no information and similar to that the program implements the PipesandFilters architecture, that a class implements the Flyweight Design Pattern, that a declared float represents feet, or that a declared String should be null. So, chances are you aren’t using one of them, look, there’re languages which can express any of these facts directly, in which case the comment is superfluous.

taxonomy Wrong, with that said, this statement is provocative and interesting. There are more good uses for comments than bad ones. Comments are an escape hatch for expressing everything about a program that the programming language can’ Comments therefore don’t fall into a single natural category.

There’s nothing to indicate if the code is the result of premature and possibly misguided optimization, or whether it actually provides some benefit to compensate for its readability and maintainability shortcomings, without this line. On p of that, if anyone decides to remove the hard won optimization, it won’t be out of ignorance, With it, the source code records its own history. Furthermore, one can start by stating the purpose of the ‘non comment’ portions of the source code, rather than stating a single purpose or use for comments. Comments are used for everything else, that is at least the following. On p of this, Noncomment’ source code is a compromise among meeting the needs of two consumers classes.

The priority given to every of these consumers depends on the context of the program’s development and deployment.

For more readable programs I use Python, an example at the degree of programming language selection is that I use C++ for ‘performance critical’ applications or deployment to ‘resourcelimited’ platforms.


Even within a specific context, the compromise is always present. In any circumstances do not express information about activities that occur before the deployed program is executed, conventional programming languages define program execution. It’s a well Other activities than execution require other artifacts. Have you heard about something like that before? Development requires examples. It’s a well Testing requires tests and contracts. Deployment requires packaging information. Now let me tell you something. Another reason for a comment is to compensate for the limits of the programming language at hand. Needless to say, There is often no way to express the design of the program within the syntax of a particular programming language. They’re less good at abstracting over types, control structures, definition patterns, or patterns of composition, and they generally lack means of describing design patterns or architecture2, Languages in mainstream use have become moderately good at abstracting over data structures.

We shall look at the inner loop of the scan convertor for a graphics library that I worked on, as an example.

This loop is responsible for drawing spans within a polygon.

A span is the portion of a scan line from the x position of an edge on the left side of the polygon’s interior to the x position of the next leftmost edge on its right. The definition of interior depends on the fill mode of the polygon. Way that this function computes the interior of the polygon is conditional on the fill mode, since a single function implements both fill modes. Nevertheless, if it does, it tests if the shape itself contains point, this code tests if the bounding box of the shape contains point. I’m sure you heard about this. The first test is redundant. It’s extra source text to read, extra code to maintain, extra code to deploy, and it breaks the Law of Demeter -it increases the coupling between this code and the implementation of the class of shape.

In my book, so that’s bad code, as it stands.

Source code is typically written only at one abstraction level.

It’s an interesting fact that the source code typically doesn’t contain both statements that express something in a highlevel or ‘coarsegrained’ way, and identical thing in a lowlevel or fine grained way, it may combine different units of structure or composition. Classes, and packages. Therefore this would be redundant, from the perspective of the compiler, after all. These artifacts can be placed in separate files. Ok, and now one of the most important parts. Often they’re ephemeral, like a test case that is typed into the command line and hereupon discarded. That they can be updated and reused as the program evolves, it’s convenient to keep these artifacts close to the program units that they describe.

Loads of them are also useful to the human reader attempting to know the program.

API documentation should’ve been rewritten to be more clean and self explanatory. All of these functions of comments as metadata could’ve been implemented by extending the language instead. Use of structured comments as metadata lets a third party ol address a gap in the language the way that leaves the source structure intact for compilers and identical source processors that wouldn’t recognize an extended grammar. Certainly, Just as comments are an escape hatch for human readers, they’re an escape hatch for development ols as well. These two comments kinds -natural language and structured metadata -are related. However, They both add information that can’t be expressed in the primary programming language. Fact, they’re both useful to humans as long as the program’s design is not evident in the source.

Another is that the key reason for an implementation decision comes from data that ain’t present in the design.

Corner cases and performance metrics are two data kinds that aren’t present in a program’s design.

Changes made in response to these data frequently result in code that’s suboptimal from a readability perspective, and that in the absence of that data would appear to be redundant. In the absence of information to the contrary, that said, this code could be optimized out, for performance and code size reasons as well as from a readability perspective. Comments are a protection against this kind of regression. Basically, Comments are also a place to put wishlist items and todos. By the way, an item can be a mistake in the code without being a mistake in the software development process, a bit of these should be mistakes in the code.

The point of software engineering is to make tradeoffs between implementation speed, implementation resources, deployment resources, and code quality. When the code is throwaway and the corner condition will never be met, when bytes count, sometimes putting all the emphasis on code quality or feature completeness is the wrong way to make the tradeoff -for example when days count, or when the enhancement was not yet useful. Comments add a choice between implementing it immediately on one hand, and ignoring it altogether on the other, when the developer knows that a corner case is present or that an enhancement is possible. As long as of its affect on the schedule and its distraction from work implementing the more important use cases, The first alternative is expensive immediately. Since it loses information that’s available now and that may have to be recreated after that,, The second is expensive later.

Leave a Reply

Your email address will not be published. Required fields are marked *