Comments help you treat source code like a product

#shorts #sourcecode #comments #programming #comment #productmanagement #productmanager #softwaredeveloper #softwaredevelopment #softwareengineer #softwareengineering #programmer #programmers

[PaulSebastianM]

I got colleagues that complain that I add comments. That code should be self explanatory, even though I am never repeating in comments what the code reads like it's doing, but always write high level 1 line comments explaining the reason why something is done this way or explain what that inner block of code is doing (when it cannot be its own function).

[bsce]

I completely agree. I’m a junior dev and when I first joined my team, my tech lead denied my PR for adding comments. He said that we shouldn’t have to write comments if our code is written concise enough. I agree our code should be clear and concise, but having comments to explain the “why’s” would really help to understand the end-to-end logic of the application. I really want to start adding more comments into the code base, do you have an suggestions or advice on how I can pushback on my tech lead and team about accepting some comments? Everyone on my team are senior devs except for me, so it is a bit intimidating.

[ChristopherCricketWallace]

I can't tell you how many devs I've worked with reject ANY code with comments.

[citizendc]

I agree with all the points you made around why it's good to add comments.

[John_Lee_]

I don't want people to understand my code

[marna_li]

That is exactly the problem: Many software developers don't see their work as a product. They go directly into coding and not understanding what they are building. It reflects in how they plan their work. Stuff that should be in place early in development are being split into tasks in different user stories. And another failure is when User Stories are treated as specifications. I'm a consultant, I don't know how common it is that the people ordering the products writes the stories - but it happens. There is also a lack of communication, as opposed to reporting status (which is often meaningless).The lack of design and modeling is also telling how well development goes. So the developers are not involved in the product, they are just asked to implement it using their technical kills. In the end, it implies uncertainties that affect the morale of the developers who perhaps desire to do more and do better.

[RetroFrequency]

There's definitely going to be companies and managers out there that don't value it. If programmers skip it so they can be faster and look good, then everyone suffers (managers lose any concept of reasonable time frames and good programmers don't have time to comment their work properly). But unfortunately this needs to be understood by the management and enforced from the top down as a result. Because otherwise managers won't recognize they're just borrowing time from the future to meet deadlines today.

[shubhodaye]

So true. As a tester I do make a point that I read the code and the comments.
Over the years, I have developed test scenarios derived from the information I gathered from reading the code.

[maximilianbeck]

Develop the product but don’t put comments on the code. They usually don’t get updated and cause more confusion than they help once the code gets older.

The best documentation of software are the tests. Try to implement functionality with test-first development. The tests will document the functionality and force the people to leave the “documentation” up to date.
Try naming objects, variables, and functions according to the functionality of the domain and also keep the data consistency of objects in line with the business domain (don’t introduce setters for everything but represent functionality in your objects).

These ways of working will prevent the next headache caused by software not working as documented in some non-code documents or comments above the code.

Whenever I have to work with software that is new to me, I read the tests first. - When there are no tests, I read the code and assume it (code + documentation) is not trustworthy. Proceeding from this step is a different story (well described in several books such as “Working effectively with legacy code” by Michael Feathers or “Refactoring” by Martin Fowler and Kent Beck).

[Wineblood]

Write code so that the cognitive load is low. Also a readme that's simple and can go from concepts to implementations without getting lost in all the files.

[johnnykernel]

dude, they don't have time for that. The only reason why they write their own code in place, just because they think they can do it faster than understand all the nuances and their version will work better on certain task. Managers will count every second, so nobody have time for nothing! You can't do a good product in a hell's race, that's the industry, so it's the result 🤷‍♂️

[nickbarton]

Forget comments, refactor it so each component is really simple.

[justice]

Depends on the language and use case. There is readable code and there is optimised code. Readable code should not have comments, only a class summery and that class no more than 150 lines.

[nezarfadle]

I would love if my code can tell a story instead of writing unnecessary comments:

Customer->Login( Credentials )->AddProductToCart( ProductDetails )->Checkout()

[Kiev-in--days]

Disagree. If you really want to help others and you future self to inderstanf rhe code quicky you must create code documentation. Schemas. Diagrams. Comments won't help that much.

[thomasf.]

Only comment what the code can't say

[BARRACUDA]

I would say not to comment, but to refactor. Because comments have a significant drawback - they very easily lose synchronization with the code.

[OneFinalTipple]

...or, take the time to express your code as clearly as a comment paragraph. It can be done. I feel that this is the case 80% of the time. Depending on the language of course. The other 20%, yes there may be no way out but to write a comment.

The advantage of clear code rather than a comment, is that code can be tested and is run in your test suite. This is not the case for comments - they can lie idle and become obsolete very quickly if they are not maintained. Also, maintaining comments and code is more time consuming than just code.