Pro CSS tip #1 (emphasis on the 'Pro' more than the 'CSS'): If you want to be a professional and work as part of a team, get better at documenting your code. Write code that other people can maintain when you're not available. Comment your code. Write actual docs. Write tests.
I disagree. I comment what my code is doing all the time, because those comments serve as 'headers' for the various tasks being performed. It's called "chunking" and it is a very powerful pattern for making things easier to understand.
Secondly: your code isn't self-explanatory, no matter how much you wish it were.
My only thing is that there are times where relatively unknown structures (to the team anyway) can be used to achieve a task. Inline comments can alleviated some time wasted doing external lookup when trying to debug something in the function:
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.
No, the original function names are better than your replacements, because they accurately describe what the functions will actually do instead of assuming they know what the user wants. Your names imply non-trivial differences in the way the functions work. These are library functions, so their names must be carefully chosen to imply only what the contract of the actual method supports. In particular:
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.
While I agree, those are all built-in functions. I suppose that's why there's the doc-on-highlight feature. I'd need to wrap them if I wanted just to rename them.
You should take the advice to mean "Don't comment on how your code is doing what it's doing, comment on why it's doing that." An English transliteration of a source code statement usually isn't very helpful.
In general I agree with you, but specifically when using comments as headers, I think it's fine to describe briefly what it's doing (and how), in the same way that a header in a book often describes what the chapter is about.
Sure, but a header in a book should just repeat the contents of the chapter but worded differently. In the same way, comments should not just reiterate the code.
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.
Comments like "add one to index" are a symptom of laziness, not of commenting about the wrong thing. As an example, here is some of my actual code:
/* 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.
That is a "useful" code smell: if the code and the comments disagree, assume both are potentially wrong, handle with extreme care, and fix ASAP where possible.
