this post was submitted on 31 May 2024
518 points (99.1% liked)

linuxmemes

19698 readers
619 users here now

I use Arch btw


Sister communities:

Community rules

  1. Follow the site-wide rules and code of conduct
  2. Be civil
  3. Post Linux-related content
  4. No recent reposts

Please report posts and comments that break these rules!

founded 1 year ago
MODERATORS
 
you are viewing a single comment's thread
view the rest of the comments
[โ€“] [email protected] 2 points 1 month ago (1 children)

I prefer concise and accurate documentation than clean code tbh. The reason is that if the documentation stated that it should perform something with side effects a,b,c then I at least know what to expect. When contributing, this also makes it easier to implement something because we have the requirement at hand. Understanding shitty code is easier than understanding human requirements. Shitty code is the language we use to talk with a computer, so at least you'll know exactly what will happen.

[โ€“] [email protected] 2 points 1 month ago

I think the same, I often find that people overestimate their ability to write self documenting code and with the added mess of automatic formatters it often becomes hard to read and understand. In my department I am one of the few who actually writes comments and readmes that explains the reason behind some decisions. I am very junior, less than a year of experience, so maybe I will be able to better understand code that other people write in the future. But for the time being I write my documentation and my comments in a way that someone who doesn't know anything about the project can understand, because I hate having to call coworkers because I can't figure out how the project handles x and y (bear in mind that is also caused by Java "best practices" with 45 abstraction layers)