▲ 1229 ▼ More the merrier (lemmy.world) submitted 3 years ago by alphacyberranger@lemmy.world to c/programmer_humor@programming.dev 75 comments fedilink hide all child comments
[–] BravoVictor@programming.dev 12 points 3 years ago (5 children) I mean… you gotta have them start the habit somehow permalink fedilink source hideshow 5 child comments replies: [–] Gallardo994@sh.itjust.works 20 points 3 years ago (2 children) Let's face it, such comments usually cause more problems than do good. If someone changes the code and forgets to modify the comment, the reader might favor one or another at random. "Stop sign" example isn't the best but you get my point. Comments at best should explain some non-obvious logic, or some sort of reasons for implementing one way or another. For SDKs and packages overall, public APIs should also be commented. The rest imo should be readable from code. permalink fedilink source parent hideshow 2 child comments replies: [–] spader312@lemmy.world 10 points 3 years ago A form of "self documentation" I like to do is create variables for conditions before using it in an if statement. If you break down a funky conditional into easy to read variables it becomes a lot more clear what it's trying to do. Idk how to write code on sync: const isHumid = xxxx; const isHot = yyyy; const isSunny = zzzzz; If (isHot && isHumid && isSunny) { ... } permalink fedilink source parent [–] coloredgrayscale@programming.dev 5 points 3 years ago If someone changes the code and forgets to modify the comment, the reader might favor one or another at random. Hence why you should comment why, not how/what. // slow down traffic before crossing busy main road Now you can change the stop sign to a yield without touching the comment. Or judge that the comment can be removed if it's clear the main road does no longer exist. permalink fedilink source parent [–] _danny@lemmy.world 11 points 3 years ago Bad/wrong documentation is worse than no documentation. "Practice makes perfect" is only true if you're practicing the right stuff. Otherwise you're just reinforcing bad habits. permalink fedilink source parent [+] bear_with_a_hammer@lemm.ee 3 points 3 years ago* (last edited 2 years ago) [deleted] permalink fedilink source parent
[–] Gallardo994@sh.itjust.works 20 points 3 years ago (2 children) Let's face it, such comments usually cause more problems than do good. If someone changes the code and forgets to modify the comment, the reader might favor one or another at random. "Stop sign" example isn't the best but you get my point. Comments at best should explain some non-obvious logic, or some sort of reasons for implementing one way or another. For SDKs and packages overall, public APIs should also be commented. The rest imo should be readable from code. permalink fedilink source parent hideshow 2 child comments replies: [–] spader312@lemmy.world 10 points 3 years ago A form of "self documentation" I like to do is create variables for conditions before using it in an if statement. If you break down a funky conditional into easy to read variables it becomes a lot more clear what it's trying to do. Idk how to write code on sync: const isHumid = xxxx; const isHot = yyyy; const isSunny = zzzzz; If (isHot && isHumid && isSunny) { ... } permalink fedilink source parent [–] coloredgrayscale@programming.dev 5 points 3 years ago If someone changes the code and forgets to modify the comment, the reader might favor one or another at random. Hence why you should comment why, not how/what. // slow down traffic before crossing busy main road Now you can change the stop sign to a yield without touching the comment. Or judge that the comment can be removed if it's clear the main road does no longer exist. permalink fedilink source parent
[–] spader312@lemmy.world 10 points 3 years ago A form of "self documentation" I like to do is create variables for conditions before using it in an if statement. If you break down a funky conditional into easy to read variables it becomes a lot more clear what it's trying to do. Idk how to write code on sync: const isHumid = xxxx; const isHot = yyyy; const isSunny = zzzzz; If (isHot && isHumid && isSunny) { ... } permalink fedilink source parent
[–] coloredgrayscale@programming.dev 5 points 3 years ago If someone changes the code and forgets to modify the comment, the reader might favor one or another at random. Hence why you should comment why, not how/what. // slow down traffic before crossing busy main road Now you can change the stop sign to a yield without touching the comment. Or judge that the comment can be removed if it's clear the main road does no longer exist. permalink fedilink source parent
[–] _danny@lemmy.world 11 points 3 years ago Bad/wrong documentation is worse than no documentation. "Practice makes perfect" is only true if you're practicing the right stuff. Otherwise you're just reinforcing bad habits. permalink fedilink source parent
[+] bear_with_a_hammer@lemm.ee 3 points 3 years ago* (last edited 2 years ago) [deleted] permalink fedilink source parent