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.
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)
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.
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)