Timeline for Ways to explain code when told it doesn't make sense
Current License: CC BY-SA 4.0
26 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Jun 21, 2020 at 14:27 | comment | added | candied_orange | "Misunderstood clean code: good code needs no comments" The key here is to realize that you are a poor judge of your own code. When you show your code to others don't explain. Listen to exactly what confused them. Do your rewrites and comments based on that. If that seems to hard it's because you waited to long to show your code to someone. Get your code reviewed while it's still fresh in your own mind. | |
| Jun 19, 2020 at 13:06 | comment | added | andydavies | My experience is that junior developers DO understand this. They come out of college or making their own projects - writing simple code, thinking about low-level details - and then they meet their senior Spring Boot Java developer with 20 years experience who writes everything like Fizzbuzz Enterprise Edition. They know it's messed up, but they don't have the experience or credentials to argue the case, they get "impostor syndrome" and they can go down one of two paths: they quit, or they acquiesce and become assimilated into the Borg. | |
| Jun 19, 2020 at 13:00 | comment | added | andydavies | This has made my day. Amazing how so few people apply the same principles. | |
| Jun 19, 2020 at 7:04 | comment | added | mtj | @yeek You will not like it, but see the last edit | |
| Jun 19, 2020 at 7:03 | history | edited | mtj | CC BY-SA 4.0 |
Added review of code samples.
|
| Jun 18, 2020 at 16:24 | comment | added | yeerk | I think a lot of these are great points in general, and issues which I have both personally experienced, and created. As an intern I worked at a company which regularly created files with over 10K lines of C++, with many functions exceeding 1K lines. As a result I both dislike overly large files... and sometimes (inadvertently) write them myself as I was forced to learn how to manage huge files (so I CAN, but shouldn't). However I am specifically interested in what appears to be more framework/non-framework abstraction complaints (which I didn't correctly emphasize in my initial question). | |
| Jun 17, 2020 at 18:59 | comment | added | mtj | @markrogers Indeed, from an architectural perspective, this is true. But then, there should be some architecture guidelines which are well known in the project, and the result should not be up to discussion. In this question, we are discussing pure code, and in this context, my recommendation stands. | |
| S Jun 17, 2020 at 18:53 | history | suggested | CommunityBot | CC BY-SA 4.0 |
gender neutral pronouns
|
| Jun 17, 2020 at 18:21 | comment | added | Mark Rogers | "don't do an extra abstraction because you might need it in the future", while I'm not sure where I stand I think some architects would take the opposite position. In that they would plan and abstract for future changes. I guess it depends on how strong "might" is and how likely one is to need an abstraction in the future. | |
| Jun 17, 2020 at 18:14 | review | Suggested edits | |||
| S Jun 17, 2020 at 18:53 | |||||
| Jun 17, 2020 at 15:24 | comment | added | Asteroids With Wings | @jmm Yeah definitely | |
| Jun 17, 2020 at 15:06 | comment | added | toolforger | There's another category: complicated logic. Particularly common in legacy code, where each tacked-on addition has another level of tacked-on addition. Here, a dose of contract commenting helps: which variable is supposed to be in what state at what point? Particularly helpful when pointing out function preconditions/postconditions, and loop invariants, but if the logic inside a function is convoluted or just nonobvious, it can help to write e.g. "at this point, numberOfValidFoos is actually the actual number of foos, we'll decrement it when we see an invalid one". | |
| Jun 17, 2020 at 14:54 | history | edited | Robert Harvey | CC BY-SA 4.0 |
deleted 3 characters in body
|
| Jun 17, 2020 at 14:39 | comment | added | jmm | I totally agree with @AsteroidsWithWings's comments, but I believe those very specific comments (which are really important) are the ones that Clean Code lists as "good comments". However, most of the times you can extract those lines that are difficult to read to a method, name it with a self explanatory name, and add additional comments in it (for example, using Javadoc/Docstring/etc). By doing so, you don't need as many comments (or maybe they can be more concise) | |
| Jun 17, 2020 at 14:28 | comment | added | Flater | "Always do the simplest thing that solves the problem at hand" This is a double edged sword and I think you might be focusing on the wrong edge for OP's sake. Some developers need to be told to not overcomplicate things, "keep things simple" is good advice here. Others need to be told to stop cutting corners and instead follow the due diligence of good practice, and "keep things simple" will be understood as justification for cutting those corners. Flawed developers can have flawed interpretations of concepts such as "simple" or "good", and we should beware of giving ambiguous advice. | |
| Jun 17, 2020 at 14:03 | history | edited | mtj | CC BY-SA 4.0 |
Hopefully clarified a point
|
| Jun 17, 2020 at 13:50 | history | edited | Robert Harvey | CC BY-SA 4.0 |
added 20 characters in body
|
| Jun 17, 2020 at 13:37 | comment | added | Asteroids With Wings | This also largely solves the "mindset" problem mentioned by others, even if your style doesn't match what your colleagues might be used to. They can adapt quickly, because they immediately know what you were thinking. | |
| Jun 17, 2020 at 13:34 | comment | added | Asteroids With Wings |
In other words, not // Switch from RGB to BGR, but // libx that we're about to pass this into expects BGR per spec §1.2, but we got RGB out of the foowhiz, so convert it now. When you worked out what you need to do and why, write it down.
|
|
| Jun 17, 2020 at 13:32 | comment | added | Asteroids With Wings | Another point about comments is that they're not there to explain what the code does; good code should be self-explanatory in that sense. But code itself sometimes can't explain why it does what it does. Why was that maths necessary? How does it relate to the problem at hand? That's what comments are for. So, just because your code is clean, doesn't mean those comments aren't needed for a proper understanding of the program. | |
| Jun 17, 2020 at 12:08 | comment | added | gnasher729 | Mtj. It happeBe that you delete a line of code that shouldn’t be there. Ho | |
| Jun 17, 2020 at 12:07 | comment | added | gnasher729 | Had a discussion with a reviewer. Reviewer: “I don’t understand this comment”. Me “If you don’t understand that comment, that’s my bug”. | |
| Jun 17, 2020 at 10:54 | comment | added | Bart van Ingen Schenau | Let me rephrase it then: You tell those people that good code also needs no explaining. The fact that you (and others) ask for an explanation is an indication that the code probably isn't good enough to do without comments. You might also refer them to commadot.com/wtf-per-minute | |
| Jun 17, 2020 at 7:37 | comment | added | mtj | @BartvanIngenSchenau That is exactly what I was trying to say. But many programmers take this misunderstood concept from clean code as an excuse, not to comment their code, even if it is not self-explanatory and definitely should be documented. | |
| Jun 17, 2020 at 6:50 | comment | added | Bart van Ingen Schenau | Re misunderstood clean code: Comments are the explanation for people reading the code in 6+ months. If an explanation is needed now, it will be needed then as well (unless the code has been cleaned up to become self-explanatory). | |
| Jun 17, 2020 at 5:31 | history | answered | mtj | CC BY-SA 4.0 |