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.
Related
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 9 years ago.
Improve this question
I had a piece of work thrown out due to a single minor spec change that turned out not to have been spec'ed correctly. If it had been done right at the start of the project then most of that work would have never have been needed in the first place.
What are some good tips/design principles that keep these things from happening?
Or to lessen the amount of re-working to code that is needed in order to implement feature requests or design changes mid implementation?
Modularize. Make small blocks of code that do their job well. However, thats only the beginning. Its usually a large combination of factors that contribute to code so bad it needs a complete rework. Everything from highly unstable requirements, poor design, lack of code ownership, the list goes on and on.
Adding on to what others have brought up: COMMUNICATION.
Communication between you and the customer, you and management, you and the other developers, you and your QA department, communication between everyone is key. Make sure management understands reasonable timeframes and make sure both you and the customer understand exactly what it is that your building.
Take the time to keep communication open with the customer that your building the product for. Make milestones and setup a time to display the project to the customer at each milestone. Even if the customer is completely disappointed with a milestone when you show it, you can scratch what you have and start over from the last milestone. This also requires that your work be built in blocks that work independent of one another as Csunwold stated.
Points...
Keep open communication
Be open and honest with progress of product
Be willing to change daily as to the needs of the customers business and specifications for the product change.
Software requirements change, and there's not much one can do about that except for more frequent interaction with clients.
One can, however, build code that is more robust in face of change. It won't save you from throwing out code that meets a requirement that nobody needs anymore, but it can reduce the impact of such changes.
For example, whenever this applies, use interfaces rather than classes (or the equivalent in your language), and avoid adding operations to the interface unless you are absolutely sure you need them. By building your programs that way you are less likely to rely on knowledge of a specific implementation, and you're less likely to implement things that you would not need.
Another advantage of this approach is that you can easily swap one implementation for another. For example, it sometimes pays off to write the dumbest (in efficiency) but the fastest to write and test implementation for your prototype, and only replace it with something smarter in the end when the prototype is the basis of the product and the performance actually matters. I find that this is a very effective way to avoid premature optimizations, and thus throwing away stuff.
modularity is the answer, as has been said. but it can be a hard answer to use in practice.
i suggest focussing on:
small libraries which do predefined things well
minimal dependencies between modules
writing interfaces first is a good way to achieve both of these (with interfaces used for the dependencies). writing tests next, against the interfaces, before the code is written, often highlights design choices which are un-modular.
i don't know whether your app is UI-intensive; that can make it more difficult to be modular. it's still usually worth the effort, but if not then assume that it will be thrown away before long and follow the iceberg principle, that 90% of the work is not tied to the UI and so easier to keep modular.
finally, i recommend "the pragmatic programmer" by andrew hunt and dave thomas as full of tips. my personal favourite is DRY -- "don't repeat yourself" -- any code which says the same thing twice smells.
iterate small
iterate often
test between iterations
get a simple working product out asap so the client can give input.
Basically assume stuff WILL get thrown out, so code appropriately, and don't get far enough into something that having it be thrown out costs a lot of time.
G'day,
Looking through the other answers here I notice that everyone is mentioning what to do for your next project.
One thing that seems to be missing though is having a washup to find out why the spec. was out of sync. with the actual requirements needed by the customer.
I'm just worried that if you don't do this, no matter what approach you are taking to implementing your next project, if you've still got that mismatch between actual requirements and the spec. for your next project then you'll once again be in the same situation.
It might be something as simple as bad communication or maybe customer requirement creep.
But at least if you know the cause and you can try and help minimise the chances of it happening again.
Not knocking what other answers are saying and there's some great stuff there, but please learn from what happened so that you're not condemned to repeat it.
HTH
cheers,
Sometimes a rewrite is the best solution!
If you are writing software for a camera, you could assume that the next version will also do video, or stereo video or 3d laser scanning and include all hooks for all this functionality, or you could write such a versatile extensible astronaut architecture that it could cope with the next camera including jet engines - but it will cost so much in money, resources and performance that you might have been better off not doing it.
A complete rewrite for new functionality in a new role isn't always a bad idea.
Like csunwold said, modularizing your code is very important. Write it so that if one piece falls prone to errors, it doesn't muck up the rest of the system. This way, you can debug a single buggy section while being able to safely rely on the rest.
Beyond this, documentation is key. If your code is neatly and clearly annotated, reworking it in the future will be infinitely easier for you or whoever happens to be debugging.
Using source control can be helpful too. If you find a piece of code doesn't work properly, there's always the opportunity to revert back to a past robust iteration.
Although it doesn't directly apply to your example, when writing code I try to keep an eye out for ways in which I can see the software evolving in the future.
Basically I try to anticipate where the software will go, but critically, I resist the temptation to implement any of the things I can imagine happening. All I am after is trying to make the APIs and interfaces support possible futures without implementing those features yet, in the hope that these 'possible scenarios' help me come up with a better and more future-proof interface.
Doesn't always work ofcourse.
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.
Question
As stated, have you any tips to help grok / understand / get-your-head-around declarative programming languages?
Or is it simply a case that you’ve to immerse yourself in the language and it’s syntax, until it seeps in, until you get that golden moment where you Get It. This isn’t really an option as I can no longer lock myself in a room for days on end, poring over half a dozen different books on the subject matter (responsibilities being what they are and all)
So, any tips or tricks that helped you when you tackled declarative languages, any insights to pass on?
P.S. I’ll personally upvote the first answer that says “Shutup and put in the work”.
Background
I was 13 years old I when I first started wring code (basic, on my sisters Oric-1).
Since then I’ve worked with many new concepts and many different languages, taking all in my stride, me taking the upper hand quickly enough. Object Orientation? Not a bother. Event driven paradigms? Smoke me a kipper, I’ll be back for breakfast.
Owl, Mfc, ActiveX, Vb3, 4, 5 & 6, VB.Net, Pascal, Delphi, C, C++ & C#. None have stood in my way, at least not for very long.
However recently my perfect score has taken a bit of a battering.
A couple of weeks ago I threw myself into Xaml, and folks, I’m more sinking than swimming.
I think my main problem is that it’s declarative. All my other programming skills are procedural. I’ve hit this block before with MSBuild, I can copy examples of how to get MSBuild things working, but would be lost putting something together from scratch.
Back to Xaml, currently I’m going insane trying to wire triggers to properties and get the effect’s I need.
I may post my specific Xaml question here soon enough. For now I’m asking this general “declarative programming” question.
P.S. No, I'm not actually this cocky. Yes, I stumbled like hell the first time I hit OO and the first time I'd to write an event driven UI (VB3 on Windows 3.11).
Edit
It's starting to sink in, the tenacity that got me this far in this field is paying off, it just takes so much fracking time!
. . . I think I'm getting too old for this stuff . . . :)
I had to teach XSL (or XSLT, as you wish) a bunch at the beginning of the century :), and it's a different world, really. That, however, is the basis for the paradigm-shift: you have to realize that declarative languages really are different. The most important advice I have is to keep studying other people's solutions, put the work in, and really try to stop thinking in FLOW. The worst thing is that, in XSL, there is an "if" and an "else," but usually there's another way to do things.
Unlike learning OO, in XSL (or any declarative language, I suppose) you will not manage to do what you're trying to do unless you do it declaratively.
So the answer is in part, "shut up and do the work" as you suggest, but the more important point is to realize that a lot of the work is getting your head around the paradigm shift. So the real answer is, "keep your eyes peeled for the paradigm shift." You have to stop thinking in flow and start thinking in terms of rules that can fire in any order... if they're done right, it doesn't matter when they fire. When you are finally thinking in rules instead of WHEN stuff happens, you're beginning to grok the shift.
Find some examples, with explanations of the "why", from someone who really knows the language. It's learning the patterns and idioms that makes a difference.
I suspect you're trying to do imperative things in declarative land, which means you think in terms of steps. Write the dataflow down in terms of required inputs + stateless function of those inputs and see if that helps.
Try a functional or functionalesqe language like ML or Scheme.
I don't know what your specific problems with Xaml are (and I haven't used it myself) , but I've found that when using XML based technologies like XSLT, a little LISP or Scheme experience can go a long way. You might want to look at playing with the excellent scheme system available free from http://www.plt-scheme.org.
I can see where this may be blowing your mind. All those languages you list are indeed quite similar (procedural).
Once you get this down, I highly encourage you to learn a functional language as well. You may also find it tough going, but learning it will help your general coding skills greatly. You'll have a whole new bag of tricks (even in procedural languages), and you will never be afraid of recursion again.
Consider your favorite “programmer ignorance” pet peeve. The first code snippet is obviously procedural. In the second snippet you make a declarative statement that for the percentage to be valid it has to be between 0 and 100.
So i'd guess you'll have no trouble grokking declarative programming languages as long as you work on it hard enough... there is no royal road to geometry
Like Binary Worrier, I had a long history with things like C, C++, MFC, etc and have been coming up to speed on XAML, WPF, and C#. I had a side trip through HTML, Javascript, and XSLT which I think helped a great deal in preparing me for XAML.
The basic idea behind XAML is fairly straightforward - it's all about what you show, not what you do. The hard part with XAML is that there is just a ton of implementation details to learn and you wind up learning them all at the same time in order to be able to get much of anything done.
I could probably be more helpful if the question was more specific.
"Programming is about giving a computer a sequence of instructions."
Most programmers react with equanimity to this statement. It's almost like... "duh?"
But the belief in this statement is what causes people to have trouble understanding other programming paradigms. It's not true, and hasn't been for a very long time. To arrive at a better understanding of programming, many may benefit from thinking on why this statement is false.
Even if you programmed in pure assembly, modern processors would rearrange your instructions, perform branch prediction, and attempt to execute multiple potentially codependent instructions at the same time. In this way they think in terms of logical dependencies, not sequences. The sequence metaphor is the false notion that an instruction logically depends on everything that preceded it. If this were true, the best way to reason about programs would be to examine the control flow. But it is not true.
It's not just declarative programming that doesn't fit with this metaphor, but also parallel and asynchronous programming.
I find the easiest way to "grok" a language is simply to start using it exclusively for all your coding. With a completely new language I would say for me the learning curve is approximately 2 weeks of coding about 4-5 hours a day. After that point it suddenly "clicks" and you can start relying less on manuals and docs.
I took a class in college (Programming Languages). It pretty much felt like I was repeatedly slamming my head against a brick wall, but about 3/4 of the way through the class, I realized the wall wasn't there anymore; I had been beating my head against nothing for a few weeks. It was a pretty surreal feeling.
I think any other way won't have the same charm. Read Godel, Escher, Bach; listen to a lot of Emerson, Lake, and Palmer and Kaikhosru Sorabji; smoke some ganja, and put in the time.
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 11 years ago.
Are there any statistics for this? I realize it must vary from person to person, but it seems like there should be a general average.
The reason I ask is that the company I contract for has multiple software products, totaling ~75,000 lines of code - and they seemed disappointed and shocked when they ask me a question about a specific portion that I don't immediately know the answer to (I am the only programmer they have, and did not author the majority of the systems) They think I should just know it all from memory. So I wanted something like a statistic to show them that an average programmer couldn't possibly have all that in his head at one time. Or should I?
You should remember where to find the needed stuff not remember it itself.
You should also be familiar with code structure and architecture enough to make an educated guess where a problem might originate and where you could possibly find the stuff you know exist but not sure where exactly.
You brain works like cache. The stuff you used recently is kept there, more older entries are erased. But there will never be enough memory to remember the code all at once. Because then you will want to remember all API functions, then all specs, then something else. This all is not feasible.
And being surprised with you that you don't remember all the code is probably one more instance of those perversed notions of how programmers do things. Ignore them.
It depends not only on your memorization skills, but also a lot on the code. Obviously, clean, idiomatic code is much easier to memorize than a badly written inconsistent mess.
Probably because clean code can be broken down into much larger "abstract tokens".
Indeed interesting question but I am in doubt if there is adequate answer at all. Here are only obvious factors I see right from the start:
Overall design quality. Even if you are new in well designed code you can very quickly identify where you should look to get answers.
Project documentation quality. For poor documented projects even developers that are in project from the start can't say anything about some parts.
Implementation quality. OK. You have good general architecture, good documentation for interfaces but even one really bad programmer could break all of this. This is because many companies are very strict about code reviews and I think it is the only one technique to prevent such situation.
Programmer experience. As you move ahead you see number of 'already known' code "bricks" in software new to you and experience is great help in this so contractors are often very experienced specialists familiar with various approaches and this gives average contractor ability to move much faster then full time programmer which is brilliant but worked 10 years in only 1 project context.
General person smartness. My opinion this is really not so important as most of others factors but it is really important.
... but the common problem is often companies hire contractors for some existing software improvement and they simply think this is only about to hang picture on the wall. You should perform some negotiation to force them to understand part of work is to understand what really should be done to meet their requirements at all. And such "learning" requires resources and is part of work itself. But I think it is slightly off-topic for StackOverflow (despite I voted up ;) ). Is it more for Startups discussion?
Even if you have written all that code you might forget portions of it. But you'll be able to recall it once you review it.
I think its natural for a programmer to forget some portions of his/her code after a long time.
Ask them how they want you to spend your time: surveying vast amounts of code you didn't write and perhaps writing up internal documentation, or whatever currently keeps you occupied It's not a facetious question. If they want quicker response to new issues, they need to invest in research.
I don't think there's a meaningful answer to this measured in LOC. As a manager, what I want to know is that someone in your situation can answer a question in a reasonable amount of time -- and unless I know you're in the middle of something, I wouldn't expect that 'reasonable amount of time' to be 'instantaneously'.
You should be able to understand all the components within the system and how they interact so that when there is a problem you can isolate one or two likely components and drill down.
I find it helpful to draw a few diagrams and keep them handy so I can use them to communicate with my boss\customer as well as jog my memory.
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 8 years ago.
Improve this question
I have always been astonished by Wine. Sometimes I want to hack on it, fix little things and generally understand how it works. So, I download the Wine source code and right after that I feel overwhelmed. The codebase is huge and - unlike the Linux Kernel - there are almost no guides about the code.
What are the best-practices for understanding such a huge codebase?
With a complex code base the biggest mistake you can make is trying to be a computer. Get the computer to run the code, and use a debugger to help find out what is going on.
Figure out how to compile, install and run your own version of Wine from the existing source code.
Learn how debug (e.g. use gdb) on a running instance of your version of Wine.
Run Wine under the debugger and make cause it to demonstrate the undesired behaviour.
The fun part: find where the code execution path goes and start learning how it all goes together.
Yes, reading lots and lots of code will help, but the compiler/debugger/computer can run code a lot faster than you.
A professor once told us to compare such a situation with climbing a mountain. You might be listening to someone who did this and tells you what it's like to look out into the country. And you believe without hesitation that that's a spectacular sight.
However, you have to start climbing yourself for real understanding what the view from the top is like.
And it's not that important to climb all the way to the top. It might be perfectly suficient just to reach a fair height above ground level.
But don't ever be afraid of start climbing. The view is always worth any efforts.
This has always been a nice analogy for me. I know this question was more about specific tips on how to efficiently deal with code bases once you started climbing. But nevertheless it instantly reminded me of our physics classes way back then.
(This is an answer I posted to a question a while back. I modified it a bit to fit this question.)
Experience has shown me that there are 3 major goals you have when learning a legacy system:
Learn what the code is supposed to do.
Learn how it does them.
(crucially) Learn why it does them the way it does.
All three of those parts are very important, and there's a few tricks to help you get started.
First, resist the temptation to just ctrl-click (or whatever your IDE uses) your way around the code to understand everything. You probably won't be able to keep everything in perspective in your mind this way, especially when each line forces you to look at multiple other classes in order to understand what it is, so you need to be able to hold several levels of the stack in your head.
Read documentation where possible; it usually helps you quickly gain a mental framework upon which to build everything that follows.
Run test cases where possible.
Don't be afraid to ask someone who knows if you have a question. Granted, you shouldn't waste others' time with inane queries, but if there's something that you simply don't understand (this is especially true with more conceptual questions like, "Wouldn't it make much more sense to implement this as a ___" or something), it's probably worth finding out the answer before you mess something up and don't know why.
When you do finally get down to reading the code, start at a logical "main" place and go from there. Don't just read the code top to bottom, or in alphabetical order, or anything (this is probably obvious).
The best way to get acquainted with a large codebase is to dive in. Many projects have a list of easy tasks that need to be done, and they're usually reserved to help ease people in. You should find and work on some of these; you'll learn a lot about the general code outline and structure, contribute to the project, and get an easy payoff that will help encourage you to take on larger tasks.
Like most projects, WINE has good resources available to its developers; IRC, wiki, mailing list, and guides/overviews. With most daunting codebases, it's not so scary after the first few fixes. WINE is truly large, and much like the kernel, I doubt there's any expert in all systems; don't feel like you need to be either. Start working on something that matters to you and take it from there.
I've started a few patches to WINE myself, and it's a good community and good structure. There's lots of very helpful debug messages, and it's a really cool project to work on, so that helps you hit it longer too.
We all appreciate your valor and willingness to help with WINE (it needs it). Thanks, and good luck.
Dig in. Think of a question you'd like to have answered, and try to find the answer. When you get tired of reading code, go read the dev mailing list, the developer's guide, or the wiki.
Unfortunately, there's no royal road to understanding a large code base. If you enjoy that sort of thing (I do) you're in for some fun. If not, guide books won't really help, so you aren't really that much worse off.
Look for one peculiar feature you are interested to improve. Search for its implementation. Once you found it, pull on that straw and all the rest will follow.
The best way is through comments.
I'm being ironic, as you understand tiny bits of the beast add comments so you can follow your trail.
The other developers will also enjoy it if you add the missing guides in the code.
Try to implement some tiny little change in the code, something that will be visible to you. That might be figuring out a workable way to output debugging statements (and figuring out where the output appears), it might be changing the default size of windows or desktop color, or something. Once you can make something happen in the codebase, you've scratched the surface of understanding and can begin to move on toward more complicated things. At that point, select a goal of something slightly more useful that you'd like the code to do, and implement that. Or check out the project's bug tracker and look for something small to start with.
Document as you go, and write unit tests as you go, and refactor as you go. When you figure out what a routine does, comment it!!
As others have suggested, dig in! Read all the available documentation you can absorb. Then see if you can find other people who are interested or knowledgeable and learn with/from them. It helps to have people to bounce ideas off of and ask questions.
For C source code, once you get a feel for what areas of the code you'd like to work on, generate ctags and cscope databases for that code. These tools make it a lot easier to jump around and understand the code. Many text editors (one example is gvim) have support for ctags and cscope so you can jump around easily.
(warning: shameless marketing ahead)
For Java developers using Eclipse, there's nWire. It is an Eclipse plugin for navigating and visualizing large codebases.
A good way to understand a large system is to break it down into it's constituent parts and focus on a specific paths through the application.
Your debugger is your friend here, set a breakpoint in the thread you want to investigate then step through it line by line looking at which each part does... hope that helps...
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 remember the old effective approach of studying a new framework. It was always the best way to read a good book on the subject, say MFC. When I tried to skip a lot of material to speed up coding it turned out later that it would be quicker to read the whole book first. There was no good ways to study a framework in small parts. Or at least I did not see them then.
The last years a lot of new things happened: improved search results from Google, programming blogs, much more people involved in Internet discussions, a lot of open source frameworks.
Right now when we write software we much often depend on third-party (usually open source) frameworks/ libraries. And a lot of times we need to know only a small amount of their functionality to use them. It's just about finding the simplest way of using a small subset of the library without unnecessary pessimizations.
What do you do to study as less as possible of the framework and still use it effectively?
For example, suppose you need to index a set of documents with Lucene. And you need to highlight search snippets. You don't care about stemmers, storing the index in one file vs. multiple files, fuzzy queries and a lot of other stuff that is going to occupy your brain if you study Lucene in depth.
So what are your strategies, approaches, tricks to save your time?
I will enumerate what I would do, though I feel that my process can be improved.
Search "lucene tutorial", "lucene highlight example" and so on. Try to estimate trust score of unofficial articles ( blog posts ) based on publishing date, the number and the tone of the comments. If there is no a definite answer - collect new search keywords and links on the target.
Search for really quick tutorials/ newbie guides on official site
Estimate how valuable are javadocs for a newbie. (Read Lucene highlight package summary)
Search for simple examples that come with a library, related to what you need. ( Study "src/demo/org/apache/lucene/demo")
Ask about "simple Lucene search highlighting example" in Lucene mail list. You can get no answer or even get a bad reputation if you ask a silly question. And often you don't know whether you question is silly because you have not studied the framework in depth.
Ask it on Stackoverflow or other QA service "could you give me a working example of search keywords highlighting in Lucene". However this question is very specific and can gain no answers or a bad score.
Estimate how easy to get the answer from the framework code if it's open sourced.
What are your study/ search routes? Write them in priority order if possible.
I use a three phase technique for evaluating APIs.
1) Discovery - In this phase I search StackOverflow, CodeProject, Google and Newsgroups with as many different combination of search phrases as possible and add everything that might fit my needs into a huge list.
2) Filter/Sort - For each item I found in my gathering phase I try to find out if it suits my needs. To do this I jump right into the API documentation and make sure it has all of the features I need. The results of this go into a weighted list with the best solutions at the top and all of the cruft filtered out.
3) Prototype - I take the top few contenders and try to do a small implementation hitting all of the important features. Whatever fits the project best here wins. If for some reason an issue comes up with the best choice during implementation, it's possible to fall back on other implementations.
Of course, a huge number of factors go into choosing the best API for the project. Some important ones:
How much will this increase the size of my distribution?
How well does the API fit with the style of my existing code?
Does it have high quality/any documentation?
Is it used by a lot of people?
How active is the community?
How active is the development team?
How responsive is the development team to bug patch requests?
Will the development team accept my patches?
Can I extend it to fit my needs?
How expensive will it be to implement overall?
... And of course many more. It's all very project dependent.
As to saving time, I would say trying to save too much here will just come back to bite you later. The time put into selecting a good library is at least as important as the time spent implementing it. Also, think down the road, in six months would you rather be happily coding or would you rather be arguing with a xenophobic dev team :). Spending a couple of extra days now doing a thorough evaluation of your choices can save a lot of pain later.
The answer to your question depends on where you fall on the continuum of generality/specificity. Do you want to solve an immediate problem? Are you looking to develop a deep understanding of the library? Chances are you’re somewhere between those extremes. Jeff Atwood has a post about how programmers move between these levels, based on their need.
When first getting started, read something on the high-level design of the framework or library (or language, or whatever technology it is), preferably by one of the designers. Try to determine what problems they are trying to address, what the organizing principles behind the design are, and what the central features are. This will form the conceptual framework from which future understanding will hang.
Now jump in to it. Create something. Do not copy and paste somebody's code. Instead, when things don’t work, read the error messages in detail, and the help on those error messages, and figure out why that error occurred. It can be frustrating, when things don’t work, but it forces you to think, and that’s when you learn.
1) Search Google for my task
2) look at examples with a few different libraries, no need to tie myself down to Lucene for example, if I don't know what other options I have.
3) Look at the date of last update on the main page, if it hasn't been updated in 6-months leave (with some exceptions)
4) Search for sample task with library (don't read tutorials yet)
5) Can I understand what's going on without a tutorial? If yes continue if no start back at 1
6) Try to implement the task
7) Watch myself fail
8) Read a tutorial
9) Try to implement the task
10) Watch myself fail and ask on StackOverflow, or mail the authors, post on user group (if friendly looking)
11) If I could get the task done, I'll consider the framework worthy of study and read up the main tutorial for 2 hours (if it doesn't fit in 2 hours I just ignore what's left until I need it)
I have no recipe, in the sense of a set of steps I always follow, that's largely because everything I learn is different. Some things are radically new to me (Dojo for example, I have no fluency in Java script so that's a big task), some just enhancements of previous knowledge (Iknow EJB 2 well, so learning EJB 3 while on the surface is new with all its annotations, its building on concepts.)
My general strategy though is I'd describe as "Spiral and Park". I try to circle the landscape first, understand the general shape, I Park concepts that I don't get just yet, don't let it worry me. Then i go a little deeper into some areas, but again try not to get obsessed with one, Spiralling down into the subject. Hopefully I start to unpark and understand, but also need to park more things.
Initially I want answers to questions such as:
What's it for?
Why would I use this rather than that other thing I already know
What's possible? Any interesting sweet spots. "Eg. ooh look at that nice AJAX-driven update"
I do a great deal of skim reading.
Then I want to do more exploring on the hows. I start to look for gotchas and good advice. (Eg. in java: why is "wibble".equals(var) a useful construct?)
Specific techniques and information sources:
Most important: doing! As early as possible I want to work a tutorial or two. I probably have to get the first circuit of the spiral done, but then I want to touch and experiment.
Overview documents
Product documents
Forums and discussion groups, learning by answering questions is my favourite technique.
if at all possible I try to find gurus. I'm fortunate in having in my immediate colleagues a wealth of knowledge and experience.
Quick-start guides.
A quick look at the API documentation if available.
Reading sample codes.
Messing around YOU HAVE TO MESS AROUND (sorry for the caps).
If it's a small library/API with a small or no community you can always contact the developer himself and ask for help 'cause he'll probably be more than happy to help you; he's happy that one more person is using his API.
Mailing lists are a great resource as long as you do your homework first before asking questions.
Mailing list archives are invaluable for most of the questions I've had on CoreAudio related stuff.
I would never read javadoc. As there often is none. And when there is, most likely it isnt up to date. So one gets confused at the best.
Start with the simplest possible tutorial you find within some minutes.
Often the tutorial will lead you to further sources at the end, so then most of the time one is on a path that goes on and on, deeper and deeper.
It really depends on what the topic is and how much info is on it. Learning by example is a good way to start a topic brand new to you, especially if you're knowledgeable in other similar libraries or languages. You can take a topic you're familiar with, and say "I understand how to implement using X, lets see how it's done using Y".
So what are your strategies, approaches, tricks to save your time?
Well, I search. I generally never ask questions, preferring to research myself. If worse comes to worse I'll read the documentation. In some cases (say, when I was doing some work with SharpSVN) I had to look at the source, specifically the test cases, to get some information about how the API worked.
Generally, I have to be honest, most of my 'study' and 'learning' is by accident.
For example, just a few seconds ago, I discovered how to get the "Recent" folder in C#. I had no idea how to do that before seeing the question, considering it interesting, and then searching.
So for me the real 'trick' is that I hang around on forums, answer questions, and accidentally pick up knowledge. Then when it comes time for me to research something; chances are I know a bit about it, and searching is easier and I can focus on the implementation [typically implementing a test program first] and progressing from there.