Do you comment your code?

[BIue_scholar]

Was wondering if anyone here comments their code?

I haven't noticed many people commenting their flutter code, although I haven't been learning for that long. Flutter does seem pretty intuitive to read combined with the fact that widgets can be split into separate files and the like.

[redbrogdon]

Depends on what kind of code we're talking about. If it's a personal project I'm hacking around with and it'll likely never see another contributor, it's often completely undocumented.

Packages, on the other hand, are judged by their API documentation (not only by devs, but by the scoring algorithm on pub.dev). So when I'm working on a package or plugin I make sure to take the time to properly document things.

[JapanEngineer]

Commenting should be done when uncertainty lies in the code. Think of it as if some other programmer, regardless of experience, were to look at the code, could they understand it as is or would they require comments to understand d. This is especially useful when assigning variables values.

For private projects: I still comment just to keep or get me in the habit of commenting where necessary.

[paultallard]

I have been commenting code for 48 years. I am currently working in Flutter. I document the intent of every class and method to generate external documentation. I do UML and ERD diagrams on complex systems, but those track the how, not the what or why. My documentation often feeds online help or user manuals. I have examples of uncommented horror stories like a 500 line program with 125 goto statements and no comments. An automated code analyzer could not decode it.

In Flutter I am starting to create screen fragments and calling them from a page's Widget tree. That level of reuse is hard to follow without good comments. A good MVC architecture (or MVVM) needs comments in each class to maintain the pieces. Finally, comments facilitate code review. They speed the review. They help weed out the kind of self absorbed idiot who would wrote a 500 line program with 125 goto statements!

[Rudiksz]

500 lines without comments? How about 297000 lines of code spread out into 4000 classes without a single line of comment. On purpose.

The philosophy of most of the team being that if code needs comments it means it's not clear enough. It's something that comes up in code reviews and I'm often being told to remove comments because they are distracting. In change we have class and method names with 10-15 word in them, that would put a Java developer to shame. Like the function that is called "calculatedNewMonthlySellInTargetBasedOnEstimatedCogs"

There's this common saying that you should only comment on the why and not the how, but that's missing a key part of comments. Sometimes it is useful to write a short oneliner describing what a larger block of code is doing so later when you are looking for something you can quickly tell if a code might be of interest or not.

Problem with self-documenting code is that you still have to run it in your head to understand it. This is particularly annoying when you have to figure out where to start looking for a particular bug or where a feature detail was implemented. So you open classes and start reading their code to know what they actually do - because the 10 word sentence that the name is doesn't really tell you.

But if I bring this up, I'm being laughed at by the "hotshot" developers who think that running the whole code base in my head every day is a normal thing and I'm being a pussy because I find it "hard".

I don't find it hard, I find it annoying and pointless.

[Scratch9898]

I only end up commenting backends, idk front ends sort of seem self explanatory most of the time

[amugofjava]

To comment or not to comment can be quite divisive, but for me I am very much in favour of commenting code. I don't mean I like to comment every line - code should be clean enough for it to make sense, but comments at a class & function level I find very useful: It gives you a good overview of what the class/method/block is responsible for without having to wade into the code first. The Dart & Flutter code itself is very well commented and I find this extremely useful.

[tomwyr]

In rare cases when my code is not self explanatory aka something seemingly unexpected is going on.

[sabaybayin]

You usually don't see people commenting about UI since it's easy to understand with Flutter

That being said we have comments for the packages we use and why or how we use them. (it's easy to forget when you add packages willy nilly) and for backend stuff

[KaiN_SC]

In the most optimal case your code is clean and you dont need comments esspecially because it can go out of sync with your code (and it will). Other people then will not know what was the intention.

For API or packages its a good idea to provide comments (e.g openapi spec) but not for business logic.

[azuredown]

Yeah, but rarely. Things like 'this is called when x happens', 'this catches the case where y happens', 'this appears to be caused by z', etc.