4 ms·
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.
by lfx 11y ago
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.
- Retra 11y agoI 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.
- smrq 11y ago$yourFavoriteLanguage already has a mechanism for chunking. They're called functions. (Okay, so if $yourFavoriteLanguage is CSS, maybe not.)
- Retra 11y agoThose functions don't always align with the problem model, and they often have a cost associated with their use.
- noxToken 11y agoMy 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.
- untog 11y agoAll three of those are just bad function names, though. Executors.instantiateThreadManager() exec.queueForAsyncExecution() exec.executeQueued() would all be a far better solution than putting an inline comment on everything.
- noxToken 11y agoWhile 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.
- jdbernard 11y agoNo, 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.
- DougWebb 11y agoYou 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.
- mercer 11y agoIn 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.
- DougWebb 11y agoSure, 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.
- Retra 11y agoComments 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.
- loco5niner 11y agoEspecially when the code is changed and the comment is now incorrect...
- Semiapies 11y agoHow do you see that working for CSS? 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.