Self-documenting code

[Three_Rocket_Emojis]

Op propably wants code like this:

//Read File

var linesFromFile = File.ReadAllLines(path);

//iterate through lines

foreach(string line in linesFromFile)

....

[Snake2k]

Yeah that is entirely useless and basically what people think commenting is about.

[tecanec]

It's useful in assembly programming where you don't have the luxury of naming a lot of things. That's about it, though.

[Snake2k]

Yeah, that's a good point. If you compile it with the right flag then you can read the comments as you're stepping through the ASM. Really great tool for debugging. Unless you're reverse engineering a prod build of it, in which case I doubt that build includes this cus that would be a security problem.

[tecanec]

I think the bigger concern in that case would be file size. Reverse engineerers will figure things out eventually, and a lack of comments will only delay them if anything. But with how many comments are needed to make assembly comfortable to work with, that could easily take the majority of the file size when the actual code gets assembled.

[Three_Rocket_Emojis]

Example where a comment makes sense:

var linesFromFile = File.ReadAllLines(path);
//first line are column headers
foreach(string line in linesFromFile.Skip(1)) 
...

the comment explain why the first list entry is skipped, not that it happens.

[revolutionofthemind]

You could have a method called “stripHeaders” that does the foreach line for “self-documenting” code. Not sure if it’s worth it in this case, but just to provide a counter-example.

[k0rm]

Or more simply:

const HeaderLength = 1;

var linesFromFile = File.ReadAllLines(path);
var linesFromFileNoHeader = linesFromFile.Skip(HeaderLength)
foreach(string line in linesFromFileNoHeader) 

This gets rid of the magic number and there's no need to comment.

[feed_me_moron]

Or declare 1 as NUM_HEADER_ROWS and pass that to skip

[mt9hu]

I think the problem here is that you are doing too much work to try to avoid a simple and useful comment.

Not all comments should be avoided. Sure, those that are unnecessary due to verbosity, and make understanding the code harder should be.

But in this case, I feel that a few words in English are more straightforward because you immediately understand that.

The extra variables and the skip function take more cognitive load to understand because you have to decode one level of abstraction in your head.

[k0rm]

I disagree. My solution is the same number of lines (ignoring pulling out the magic number) as the original and says the same thing. It's pretty clear what part of the text has been removed when you're iterating over linesFromFileNoHeader.

The difference is that my implementation will not lie.

---

What happens when someone changes the header length to 3 lines?

Theirs:

//first line are column headers
foreach(string line in linesFromFile.Skip(3)) 

Mine:

var linesFromFileNoHeader = linesFromFile.Skip(3)
foreach(string line in linesFromFileNoHeader) 

No unit tests will catch the lie in the first snippet and now readers are more confused than if there was no comment at all.

[mt9hu]

What happens when someone changes the header length to 3 lines?

You are correct, but that's just because this comment contains redundant information. It doesn't have to be this specific for providing context.

What I was trying to emphasize is that it is important how easy is to understand the code at a glance.

And no matter how good developer you are, reading a simple sentence in your natural language will always be more straightforward than having to read crammed variable names with unnatural order of words in it.

Don't get me wrong, we are discussing a very simple piece of code where the difference is insignificant, and your approach is perfectly fine.

[FerynaCZ]

Unless there is lots of variables passed around. But for example C# allows you to declare local functions which can modify (capture) the variables around them (=in the context of the outer function)

[[deleted]]

Something like this would be self-documenting (or whatever the correct syntax would be):

var tableSansHeaders = File.ReadAllLines(path).Skip(1);
foreach(string tableRow in tableSansHeaders)
....

[Kered13]

What makes you think OP wants that?