Pro Tip 1.1 -> Do not comment what your code is doing (code should be self-explanatory). Comment why something is done this or that way.
Secondly: your code isn't self-explanatory, no matter how much you wish it were.
(Okay, so if $yourFavoriteLanguage is CSS, maybe not.)
ExecutorService exec = Executors.newSingleThreadExecutor(); //instantiate thread manager
Future<?> future = exec.submit(serviceTimer); //queue thread for async execution
exec.shutdown(); //execute queued thread and deny additional requests for execution
All of these inliners are explained in the docs, but sometimes it gives a warm and fuzzy when the author explicitly states what is happening with a comment. Executors.instantiateThreadManager()
exec.queueForAsyncExecution()
exec.executeQueued()
would all be a far better solution than putting an inline comment on everything. Executors.instantiateThreadManager()
You lose information about the thread count (single thread). Also, a nitpick I know, but in Java new means instantiate, so just say new and save typing. Also, an executor is not guaranteed to be a thread manager in any meaningful sense. It is only guaranteed to be an Executor. exec.queueForAsyncExecution()
This may not actually be async. 9/10 it is, but the interface does not guarantee async, just a de-coupling from queuing and execution. exec.executeQueued()
This misses the fact that calling shutdown will deny future tasks from being queued after it is called.This is actually a great example of why function names are not a sufficient replacement for appropriate comments.
In the header case, the comment is a summary of what the code is doing, which I think is fine if it allows you to understand the code block quickly without reading it in detail. That's different from a comment like "Add one to index" followed by "index = index+1", which is the canonical/trivial example of what the advice is intended to recommend against.
/* Prompt for scheduler. */
if (!flag_scheduler_selected && !flag_no_prompts) {
option_scheduler = prompt_scheduler();
}
The purpose of the comment is not to tell you what it is doing or why I'm doing it. The comment is there to tell you that what I am doing now has nothing to do with what came before. It signals a mental context switch. Without the comment, you wouldn't be able to easily scan the code and see where different things are happening.Is this:
/* This should have round corners */
.this {
border-radius:2em;
}
any better than this? /* Make this have round corners */
.this {
border-radius:2em;
}
Really, I look at the boilerplate how-to-comment discussion thread here, and it seems utterly irrelevant to CSS.