What if you need to explain business rules? For example, we can't store fuel in this type of warehouse, this is why we need to do this check..
What if you explain some unexpected behaviour in other system? For example, we need to put pause here because our hardware is not able to proceed signals so fast.
What if you need to explain some unobvious code trick? For example, we use modified version of original Dijkstra algorithm, it is a bit slower, but takes less memory.
It is not just "why", sometimes it is "what". For example, we write a small library for visualization. We use the term "frame" there. Can you guess what is it? If you will search the internet for "frame programming" it will give you "stack frame", "frames per second". The term "frame" in my case comes from "The Grammar of Graphics" (similar to Pandas DataFrame), would you prefer if I put an explanation of the term "frame" in the comment or not?
we can't store fuel in this type of warehouse, this is why we need to do this check
Then you use structures in your paradigm(s) that express this in an intuitive way. For example in OOP we extend (or compose I guess) Warehouse with a FuelessWarehouse. Contrived example but still, better than comments and doesn't rely on someone to read, follow and maintain comments and avoids issues caused by out of date comments.
we need to put pause here because our hardware is not able to proceed signals so fast
Then again you express it using your paradigm of choice by using threads/futures/objects that convey this in a verifiable way and if that fails, a test which describes the behaviour then it can't simply be ignored.
we use modified version of original Dijkstra algorithm, it is a bit slower, but takes less memory.
In this case it's just organisation, it's called using a memoryOptimisedDijkstra() and no comment necessary.
Example with business rules. I agree with you here.
Example with code trick (memoryOptimisedDijkstra) we agreed that we can put comment in the top of the function, which is out of your question because you ask only about comments iniside the block.
What if you explain some unexpected behaviour in other system? For example, we need to put pause here because our hardware is not able to proceed signals so fast.
No, it isn't. Even this hack is better than a comment
fun doSomething(Operation o, Evnironment e){
if (e.isSlow(){
slowO = SlowHardwareDelayOperationFactory.create(o)
slowO.perform();
}else{
o.perform();
}
}
because
a: it is verifiable, we can write a test to say if the environment is slow we add a delay, unlike a comment
b: it is self documenting
c: it's reusable, unlike a comment
d: if we no longer need the delay and remove it, there's no comment to clean up
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
What if you need to explain business rules? For example, we can't store fuel in this type of warehouse, this is why we need to do this check..
What if you explain some unexpected behaviour in other system? For example, we need to put pause here because our hardware is not able to proceed signals so fast.
What if you need to explain some unobvious code trick? For example, we use modified version of original Dijkstra algorithm, it is a bit slower, but takes less memory.
It is not just "why", sometimes it is "what". For example, we write a small library for visualization. We use the term "frame" there. Can you guess what is it? If you will search the internet for "frame programming" it will give you "stack frame", "frames per second". The term "frame" in my case comes from "The Grammar of Graphics" (similar to Pandas DataFrame), would you prefer if I put an explanation of the term "frame" in the comment or not?
Then you use structures in your paradigm(s) that express this in an intuitive way. For example in OOP we extend (or compose I guess)
Warehouse
with aFuelessWarehouse
. Contrived example but still, better than comments and doesn't rely on someone to read, follow and maintain comments and avoids issues caused by out of date comments.Then again you express it using your paradigm of choice by using threads/futures/objects that convey this in a verifiable way and if that fails, a test which describes the behaviour then it can't simply be ignored.
In this case it's just organisation, it's called using a
memoryOptimisedDijkstra()
and no comment necessary.like this?
How did you get from
to
^ where is the comment required?
Example with business rules. I agree with you here.
Example with code trick (
memoryOptimisedDijkstra
) we agreed that we can put comment in the top of the function, which is out of your question because you ask only about comments iniside the block.This one is still valid use-case.
No, it isn't. Even this hack is better than a comment
because
a: it is verifiable, we can write a test to say if the environment is slow we add a delay, unlike a comment
b: it is self documenting
c: it's reusable, unlike a comment
d: if we no longer need the delay and remove it, there's no comment to clean up