Discussion on: Should comments in code be considered failures in coding?

View post

Replies for: Not at all. If you feel like you need to explain something. It's possible it's not acting in an intuitive way and some failure in method has occu...

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.

stereobooster • Aug 26 '19 • Edited

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?

Ross • Aug 26 '19

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.

stereobooster • Aug 26 '19

doubleCheckIfThisFuelBecauseWeCantStoreItWithoutFireAlarm();

putPauseBecauseBugInZeexel2000MA();

aBitSlowerButMemoryOptimisedDijkstraBecauseWeSkipHeapAllocation();

like this?

Ross • Aug 26 '19 • Edited

How did you get from

For example in OOP we extend (or compose I guess) Warehouse with a FuelessWarehouse

doubleCheckIfThisFuelBecauseWeCantStoreItWithoutFireAlarm()

fun storeFuel(Item item, Warehouse warehouse) throws FireSafetyException{
 if (item instanceOf Fuel && !warehouse.hasFireAlarm()){
   throw FireSafetyException("Not equiped for fire safety")
 }
}

^ where is the comment required?

stereobooster • Aug 27 '19

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.

This one is still valid use-case.

Ross • Aug 27 '19 • Edited

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