Related
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I've realised that my greatest weakness as a programming student is my poor ability to comprehend other people's code.
I have no trouble whatsoever with 'textbook' code, or clearly-commented code, but when given a program of a few hundred lines, containing a dozen or so different functions and no comments, I find it very difficult to even begin.
I know this type of code is what I'm probably more likely to encounter in my career, and I think that having poor code comprehension skills is going to be a great hindrance to me, so I'd like to focus on improving my skills in this area.
What tools/techniques have helped improve code comprehension in your experience?
How do you tend to tackle unfamiliar, uncommented code? Why? What about your technique do you find helpful?
Thanks
Familiarizing yourself with foreign code
If the codebase is small enough, you can start reading it straight away. At some point the pieces will start falling together.
In this scenario, "small enough" varies, it will get larger as your experience increases. You will also start benefiting from "cheating" here: you can skip over pieces of code that you recognize from experience as "implementing pattern X".
You may find it helpful to make small detours while reading the code, e.g. by looking up a function as you see it being called, then spend a little time glancing over it. Do not stay on these detours until you understand what the called function does; this is not the point, and it will make you feel like you are jumping around and making no progress. The goal when detouring is to understand what the new function does in less than half a minute. If you cannot, it means that the function is too complicated. Abort the detour and accept the fact that you will have to understand your "current" function without this extra help.
If the codebase is too large, you can't just start reading it. In this case, you can start by identifying the logical components of the program at a high level of abstraction. Your goal is to associate types (classes) in the source code with these components, and then identify the role each class plays in its component. There will be classes used internally in a component and classes used to communicate with other components or frameworks. Divide and conquer here: first split the classes into related groups, then focus on a group and understand how its pieces fit together.
To help you in this task, you can use the source code's structure as a guide (not as the ultimate law; it can be misleading at times due to human error). You can also use tools such as "find usages" of a function or type to see where each one is referenced. Again, do not try to fully digest what the IDE tells you if you can't do it reasonably quickly. When this happens, it means you picked a complicated piece of metal out of a machine you don't quite understand. Put it back and try something else until you find something that you can understand.
Debugging foreign code
This is another matter entirely. I will cheat a little by saying that, until you amass tons of experience, there is no way you will be debugging code successfully as long as it is foreign to you.
I find that drawing the call-graph and inheritance trees out often works for me. You can use any tool you have handy; I usually just use a whiteboard.
Usually, the code units/functions are easy enough to understand on their own, and I can see plainly how each unit operates, but I often times have trouble seeing the bigger picture, and that's where the breakdown happens and I get this "I'm lost" feeling.
Start small. Say to yourself: "I want to accomplish x, so how is it done in the code?" where x is some small operation that you can trace. Then, just trace the code, making something visual that you can look back on after the trace.
Then, pick another x and repeat the process. You should get a better feel for the code every time you do this.
When it comes time to implement something, choose something that is similar (but not almost identical) to one of the things you traced. By doing this, you go from a trace-level understanding to an implementation-level understanding.
It also helps to talk to the person who wrote the code the first time.
The first thing I try and do is figure out what the purpose of the code is at a high-level -- the detail's kind of irrelevant until you understand a bit about the problem domain. Good ways to figure that out include looking at the names of the identifiers, but it's usually even more helpful to consider the context -- where did you get this code? Who wrote it? Was it part of some application with a known purpose? Once you've figured out what the code's supposed to do, you can make a copy and start reformatting it to make it easier for you personally to understand. That can include changing the names of identifiers where necessary, sorting out any weird indentation, adding whitespace to break things up, commenting bits once you've figured out what they do, etc. That's a start, at any rate... :)
Also -- once you've figured out the purpose of the code, stepping it through a debugger on some simple examples can also sometimes give you a clearer idea of what's going on FWIW...
I understand your frustration, but keep in mind that there is a lot of bad code out there, so keep your chin-up. not all code is bad :)
this is the process that I tend to follow:
look for any unit tests as they should document what the code is supposed to do...
navigate through the code using code rush / resharper / visual studio shortcuts - this should give you some ideas about the logical and physical tiers involved...
scan the code first, looking for common patterns, naming conventions, and code styles - this should give you insight into the teams standards and maybe the original coders mind set...
as I navigate through the code heirarchy I make a note of the the objects being used... typically with pen & paper drawing a simple activity diagram :
I tend to start from a common entry point, so if it is a UI, start from the view and work your way through to the data access code, if its a service start from the service boundary and work your way through to the data access code...
look for code that could be refactored - if you can see code that can be refactored, you have learned how to simplify it without changing its behavior...
practice building the same thing that you are reviewing, but in a different way...
as you read through untested code, think of ways to make it testable...
use code rush diagnostics tools to find methods that are of high maintenance complexity or cyclomatic complexity and pay special attention to these areas because chances are, this is where the most bugs are...
Good luck
Understand is a terrific code analysis tool. It was in wide use at my previous employer (L-3) so I purchased it where I currently work.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I've come across an article that discusses the issue of "code admiration". Basically, the author talks about how developers should be more skeptic about code they write. How we may "admire" our code too much, attach our-self to it, making us more vulnerable to bugs and other mishaps that may be lying in front of us.
How do you feel about this issue? And do you have more tips on how to avoid/be more aware of this issue?
Some years ago, I was working with another on a small "hobby" project, and I realised that we had to re-assess things. We had written lots of code but it wasn't all good code.
We didn't really want to "throw away" all the work we had put in. But I realised something: what mattered most was the amount of work we would need to put in from now on.
We couldn't change the fact that we had already put so much work into the project, so the only way to minimise the total amount of work the project would need, would be to minimise the amount of work we hadn't done yet.
Since that day, I have stopped being attached to my code. If I'm confident that throwing it away and starting from scratch means less work than keeping it and adapting it to my needs, then I'll throw it away.
My high school art teacher used to encourage us to take what we considered to be our best drawings and tear them up; he called this "cleansing the soul". His reasoning was that, as artists, we were driven to create works of art, and any time we produced something that we liked and that gave us satisfaction, our motivation to continue creating would be lessened.
So I followed his advice and tore up my best stuff, and it worked. Instead of spending my time admiring my old work, I created new stuff and continually got better. I've tried to follow the same principle with my code, but it doesn't really work: my computer has a tough plastic shell that is nearly impossible to tear through.
I post a fragment from Jeff Atwood's blog, Sucking Less Every Year, and I agree 100%.
I've often thought that sucking less
every year is how humble programmers
improve. You should be unhappy with
code you wrote a year ago. If you
aren't, that means either A) you
haven't learned anything in a year, B)
your code can't be improved, or C) you
never revisit old code. All of these
are the kiss of death for software
developers.
We sure like to admire our nice code, but it's not always easy to know what to admire. Complicated and elaborate code is sometimes mistaken for admirable code, while elegance and simplicity should rather be what to strive for.
Two quotes come to mind:
"Debugging is twice as hard as writing
the code in the first place.
Therefore, if you write the code as
cleverly as possible, you are, by
definition, not smart enough to debug
it.”
-- Brian Kernighan
and
"Make everything as simple as
possible, but not simpler."
-- Albert Einstein
Jonathan Edwards wrote an impressively beautiful essay on this subject, prompted by the work on the O'Reilly book Beautiful Code. Here's the final paragraph, but the rest of the essay is also worth reading.
Another lesson I have learned is to distrust beauty. It seems that infatuation with a design inevitably leads to heartbreak, as overlooked ugly realities intrude. Love is blind, but computers aren’t. A long term relationship – maintaining a system for years – teaches one to appreciate more domestic virtues, such as straightforwardness and conventionality. Beauty is an idealistic fantasy: what really matters is the quality of the never ending conversation between programmer and code, as each learns from and adapts to the other. Beauty is not a sufficient basis for a happy marriage.
Other versions of this same wisdom exist in other fields. Samuel Johnson, about writing:
Read over your compositions, and wherever you meet with a passage which you think is particularly fine, strike it out.
William Faulkner's version of this was much more succinct: “Kill your darlings.”
My father-in-law works as a film editor, and he studiously avoids the set where the film is being shot. When he does have to visit, he shields his eyes as much as he can. This is because when he decides whether or not to include a scene in the final film, he doesn't want to be influenced by how much effort it took to shoot the scene. What matters is how well the scene works in the final film.
My essay, "My evolution as a programmer" (which I would link to if I weren't a new user), is largely about learning skepticism about the code I'd written: whether it works, whether it's useful, whether it's comprehensible (pair programming was a real wake-up call here). It's hard!
I never admire my code. I admire other peoples code that i "borrow" and try and emulate them or better them and i find that the more i know, especially about coding the more i find i don't to know. The only thing of value wold be for peer programmers to admire my code and borrow it.
I think he has a good point. It's frustrating to work with people that have too much of this, as it really hinders teamwork and getting to the best solution to the problem.
As I can be a bit delusional, I try to put practices in place that will keep me grounded in reality. For code,
unit tests: These keep me more focused on what the code is supposed to do, as opposed to any abstract "beauty".
shared code ownership: There are two camps here: give people more ownership of their code and hope pride takes over, or give them less and let peer pressure come into play. I believe that giving people more ownership can lead to this code admiration. We practice shared code ownership, so I am constantly forced to see someone rewrite my perfect code to make it better (in their mind). I quickly realized admiring it too much was a waste of time and emotionally difficult.
pair programming: working side-by-side with someone will keep you realistic.
other feedback: These are all feedback loops, but there are others. There's no better way to see if something works than by watching someone (try to) use it. Put your work in front of as many people as possible. Have code reviews. Read other people's code. Run static code analysis tools.
I'm with PurplePilot - I don't admire my own code, and as such I'm constantly searching for new, more efficient (hell, easier) ways of doing the same thing. I like the Effective c# book, picked up lots of useful code from there that I admire.
I would have no hesitation about throwing code away and starting again, but not necessarily from scratch, i.e. by writing some code for a specific scenario and then throwing it away, you'll probably have a better grasp of the scenario. In other words, it's a "wicked problem", or you've found another way that doesn't work a la Edison.
It begs a wider question: if code isn't thrown away, or at least revisited, is developing on libraries that are becoming stagnant a good thing?
There is nothing wrong with admiring your code ... this is part of the positive reinforcement process that will motivate you to write more and better code in the future.
However, misplaced or misused admiration can be a problem. If the code is really not good, or has bugs that haven't been exposed by unit or other testing, or needs refactoring/redesign/replacement then this misplaced admiratoin is a problem. And using admiration as an excuse to skip part of the process - such as code reviews, or not having a skeptical attitude towards code - is misuse of admiration.
Like anything else that is good, admiration of code can be misplaced or misused - it doesn't mean that it in itself is bad. That would be like saying "religion is a bad thing, because it causes conflicts and wars between people".
Two words: code review.
Gather two or more fellow developers and invite them to review/criticize/comment on your code. 'twill shed some (admittedly harsh) light on your code.
It's perhaps better to have a healthier perspective - we aren't rocket scientists, and we aren't curing cancer - it's just work.
(Yes, it's reasonable to be proud of an entire building you helped build if you're an architect, but do they really have a lot of their self-esteem wrapped up in an individual blueprint, or a closet on floor 3 they designed by themselves?).
What are some ways in which I can write code that is easily modified?
The one I have learned from experience is that I almost always need to write one to throw away. That way I have developed a sense of the domain knowledge and program structure required before coding the actual application.
The general guidelines are offcourse
High cohesion, low coupling
Dont repeat yourself
Recognize design patterns and implement them
Dont recognize design patterns where they are not existing or necassary
Use a coding standard, stick to it
Comment everyting that should be commented, when in doubt : comment
Use unit tests
Write comments and tests before implementation, that way you know exactly what you want to do
And when it goes wrong : refactor, refactor, refactor. With good tests you can be sure nothing breaks
And oh yeah:
read this : http://www.pragprog.com/the-pragmatic-programmer
Everything (i think) above and more is in it
I think your emphasis on modifiability is more important than readability. It is not hard to make something easy to read, but the real test of how well it is understood comes when someone else (or you) has to modify it in repsonse to changing requirements.
What I try to do is assume that modifications will be necessary, and if it is not really clear how to do them, leave explicit directions in the code for how to do them.
I assume that I may have to do some educating of the reader of the code to get him or her to know how to modify the code properly. This requires energy on my part, and it requires energy on the part of the person reading the code.
So while I admire the idea of literate programming, that can be easily read and understood, sometimes it is more like math, where the only way to do it is for the reader to buckle down, pay close attention, re-read it a few times, and make sure they understand.
Readability helps a lot: If you do something non-obvious, or you are taking a shortcut, comment. Comments are places where you can go back and refactor if you have time later. Use sensible names for everything, makes it easier to understand what is going on.
Continuous revision will let you move from that first draft to a better one without throwing away (too much) work. Any time you rewrite from scratch you may lose lessons learned. As you code, use refactoring tools to eliminate code representing areas of exploration that are no longer needed, and to make obvious things that were obscure. The first one reduces the amount that you need to maintain; the second reduces the effort per square foot. (Sqft makes about as much sense as lines of code, really.)
Modularize appropriately and enforce encapsulation and separation of logic between your modules. You don't want too many dependencies on any one part of the code or that part becomes inherently harder to understand.
Considering using tried and true methods over cutting edge ones. You give up some functionality for predictability.
Finally, if this is code that people will be using before and after modification, you need(ed) to have an appropriate API insulating your code from theirs. Having a strong API lets you change things behind the scenes without needing to alert all your consumers. I think there's a decent article on Coding Horror about this.
Hang Your Code Out to D.R.Y.
I learned this early when assigned the task of changing the appearance of a web-interface. The code was in C, which I hated, and was compiled to a CGI executable. And, worse, it was built on a library that was abandoned—no updates, no support, and too many man-hours put into its use to change it. On top of the framework was a disorderly web of code, consisting of various form and element builders, custom string implementations, and various other arcane things (for a non-C programmer to commit suicide with).
For each change I made there were several, sometimes many, exceptions to the output HTML. Each one of these exceptions required a small change or improvement in the form builder, thanks to the language there's no inheritance and therefore only functions and structs, and instead of putting the hours in the team instead wrote these exceptions frequently.
In my inexperience I was forced to change the output of each exception, rather than consolidate the changes in an improved form builder. But, trawling through 15,000 lines of code for several hours after ineffective changes would induce code-burn, and a fogginess that took a night's sleep to cure.
Always run your code through the DRY-er.
The easiest way to modify a code is NOT to write code. Write pseudo code not just for algo but how your code should be structured if you are unsure.
Designing while writing code never works...for me :-)
Here is my current experience: I'm working (Java) with a kind of database schema that might often change (fields added/removed, data types modified). My strategy is to parse this schema and to generate the code with apache velocity. The BaseClass generated is never modified by the programmer. Else, a MyClass extends BaseClass is created and the logical components of this class (e.g. toString() ! )are implemented using the 'getters' and the 'setters' of the super class.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Recently, we've come across an issue at work where if one person is working on some code by themselves, it seems to come out with the other team members looking at it and going "Huh? That's ugly, unmanageable, I need to rewrite that"
In fact, recently, I myself have had to re-factor something that was written the week before so that I'd be able to add in my (related) feature.
I know that Pair programming is the way to go for this, but we have an uneven team (3 members). As our team is being pushed pretty hard at the moment, we really don't have time for Peer Reviews (though we can do Pair Programming, as we're allowed to estimate that into our task estimates)
I'm just curious as to how people would suggest we overcome these issues with poor code being generated.
When you work alone, and produce code which your colleagues find ugly and unmanageable and needs to be rewritten, then do you:
(a) agree with them when you look at it a second time,
(b) disagree?
If (a), then the problem is that on your own, you aren't fully clarifying your code when you write it. Since pair programming is the only thing making you write decent code, I suppose I'd recommend that the "odd one out" should work on tasks which do not involve writing long tracts of bad code: bug-hunting; maybe writing test code, since that tends to be a bit less fiendish. Meanwhile, work on improving your skills at writing better code - perhaps do reviews of your own code from a few months ago, and make notes as to what was wrong with it.
If (b), then the problem you have is incompatible ways of expressing your ideas. The code may not be bad by your standards, but it's mutually incomprehensible, which in a corporate setting means it's bad code. Pair programming means what you write is a compromise that 2 out of 3 of you understand, but that's not really a solution. You need to come to some mutual agreements about what you find most difficult about each other's code, and stop doing that. And you all urgently need to start thinking of "code quality" in terms of "my 2 colleagues will like this code", not "I like this code".
Either way, you all need to work on writing code for the purpose of being read, rather than for the purpose of getting the immediate job done as quickly as you possibly can. Personally I have done this by trying to express things in the way that I think other people might express and understand them, rather than just what makes sense to me at the time. Eventually it becomes habitual. When I write code, I write it for a public audience just like I'm writing this post for a public audience. OK, so on my personal projects it's an audience of people who think just like me, whereas at work it's an audience that thinks like my colleagues. But the principle is to write code as if someone's reading it. You're explaining yourself to them, not the compiler.
Not that my code is the best in the world, but I do think I benefited in that my first job was in a company with 30-odd programmers, so I got to see a wide range of ways of thinking about things. Also a few examples of "what not to do", where one programmer had done something that nobody else could easily understand, and therefore could definitively be said to be bad. With only 3 people, it's not clear whether a 2 v. 1 difference of opinion means that the 1 is a freak or a reasonable minority. When I did something and 4 or 5 people could glance at it and immediately say "eeew, don't do that", then I started to really believe it was just a dumb idea in the first place.
I'd also recommend that if you aren't allowed to budget for code review, lie and cheat. If you're heavily re-writing someone else's code, you're effectively taking the time to review it anyway, you just aren't providing the feedback which is the worthwhile part of code review. So sneak the review in under the radar - write a function or three, then ask a colleague to look at it and give you instant feedback on whether it makes sense to them. It helps to have a conversation as soon as you've done it, with the code on the monitor, but do try not to interrupt people when they have "flow", or to get into lengthy arguments. It's not pair programming, and it's not formal code review, but it might help you figure out what it is you're doing on your own that's so bad.
I'm surprised that you don't have time to do peer reviews but you have time to do paired programming. Is the latter not a much bigger sink of time?
We also have three developers only at our company and, surprise, surprise, we're being pushed hard at the moment. I'm pretty sure my boss would laugh at me if I suggested paired programming because that would be viewed as doubling the number of man hours for a task even though in practice that's not the result it should produce. Our peer reviews are never more than an hour and that is an extreme case. On average I would say they are probably about 10 minutes and, per developer, only happen once or twice in a day.
IMO you should give peer reviews a try. You often find that the offending people (i.e. the people writing the lower quality code) eventually realise that they need to make more of an effort and the quality improves over time.
If you have three developers and each of you think the others code is not good, you urgently need peer reviews.
So:
you are being pushed pretty hard
your code is of poor quality
Do you think the two could possibly be related? The answer is to fix the schedule.
Pair up all three at once.
Set up some coding standards.
Use a dunce cap for build breaking developers.
Perform daily stand up meetings to communicate progress.
Also try peer reviews twice a week, like Tuesday and Friday.
Pair Programming doesn't have to be all day every day to be effective. I have seen good results from even an hour or two working together each week. One way to go would be to pair A & B for a while, then A & C, then A & B... with a lot of individual time in between.
It also depends a lot on the personalities and chemistry of the team members. Two of the three might work exceptionally well together and you'd want to benefit from that.
You should still pair. Set up sessions say 1 day per week and rotate the pairs. This should keep your manager happy and increase the quality of the code, improve communication. If you keep metrics on how many faults happen in paired vs solitary coding you should start to see the benfit and display this to your manager,
eg This took x man hours but saved on average y in defect fixing. Additionally the clode is cleaner and will take less time to alter then next time we touch it.
From there you will have hard statistics and you can start to code more.
Basically your story seems to be the same as mine.
No time to do things.
Mistakes happen.
Rush to fix it (taking more time)
Go to 1
You need to stop the rot.
Code reviews
Enable Stylecop that will force you to write readable, standardised and manageable code
We use code reviews. Additionally there are some single task: changing a diagram, installing some stuff...
Do they contradict?
Decoupling is something great and quite hard to achieve. However in most of the applications we don't really need it, so I can design highly coupled applications and it almost will not change anything other than obvious side effects such as "you can not separate components", "unit testing is pain in the arse" etc.
What do you think? Do you always try to decouple and deal with the overhead?
It seems to me decoupling and YAGNI are very much complementary virtues. (I just noticed Rob's answer, and it seems like we're on the same page here.) The question is how much decoupling you should do, and YAGNI is a good principle to help determine the answer. (For those who speak of unit testing -- if you need to decouple to do your unit test, then YAGNI obviously doesn't apply.)
I really sincerely doubt the people who say they "always" decouple. Maybe they always do every time they think of it. But I have never seen a program where additional layers of abstraction couldn't be added somewhere, and I sincerely doubt there is a non-trivial example of such a program out there. Everyone draws a line somewhere.
From my experience, I've deoupled code and then never taken advantage of the additional flexibility about as often as I've left code coupled and then had to go back and change it later. I'm not sure if that means I'm well-balanced or equally broken in both directions.
YAGNI is a rule of thumb (not a religion). Decoupling is more or less a technique (also not a religion). So they're not really related, nor do they contradict each other.
YAGNI is about pragmatism. Assume you don't need something, until you do.
Usually assuming YAGNI results in decoupling. If you don't apply that knife at all, you end up assuming that you need to have classes that know all about each other's behavior before you have demonstrated that to be true.
"Decouple" (or "loosely couple") is a verb, so it requires work. YAGNI is a presumption, for which you adjust when you find that it's no longer true.
I'd say they don't. Decoupling is about reducing unnecessary dependencies within code and tightening up accesses through clean, well-defined interfaces. "You ain't gonna need it" is a useful principle which generally advises against over-extensibility and overly broad architecture of a solution where there's no obvious and current use case.
The practical upshot of these is that you have a system where it's much easier to refactor and maintain individual components without inadvertently causing a ripple effect across the entire application, and where there are no unnecessarily complicated aspects to the design - it's as simple as is required to meet the current requirements.
I (almost) always decouple. Every time I did this I found it useful, and (almost) every time I didn't I had to do it later. I've also found it a good way to decrease the number of bugs.
Decoupling for the sake of decoupling can be bad.
Building testable components is very important though.
The hard part of the story is to know when and how much decoupling you need.
If "unit testing is a pain in the arse" then I would say that you do need it. Most of the time decoupling can be achieved with virtually zero cost as well, so why wouldn't you want to do it?
Furthermore, one of my biggest bugbears when working on a new codebase is having to decouple the code before I can start writing unit tests when the introduction of an interface somewhere or use of dependency injection could save alot of time
As your tag says, it's highly subjective. It rests entirely upon your own engineering wisdom to decide what you "ain't gonna need". You may need coupling in one case, but you won't in another. Who is to tell? You, of course.
For a decision so subjective, then, there cannot be a guideline to prescribe.
Well, YAGNI is little more than a bogus simplistic phrase people throw around. Decoupling, however, is a fairly well understood concept. YAGNI seems to imply that one is some sort of psychic. It's just programming by cliche, which is never a good idea. To be honest, there is a case to be made that YAGNI is probably not related to decoupling at all. Coupling is typically "quicker" and "who knows if you are you are going to need a decoupled solution; you aren't gonna change X component anyway!"
YAGNI the mess :) ... really, we don't need to have all the code mixed to go "faster".
The unit tests really help on feeling when it is coupled (given one understand well what is an unit test vs. other types of tests). If you instead do it with the "you can not separate components" mindset, you can easily get to add stuff that you ain't gonna need :)
I would say YAGNI comes in when you start twisting and changing logic all around beyond the actual usage scenarios the current implementation calls for. Lets say you have some code that uses a couple external payment providers that both work with redirects to an external site. It is ok to have a design that keeps everything clean, but I don't think it is ok to start thinking of providers that we don't know if will be ever supported that have plenty of different way of handling the integration and the related workflow.