|
Sadly this is very true. When there is a clock ticking down the profit margins, documentation is usually the first casualty.
We're philosophical about power outages here. A.C. come, A.C. go.
|
|
|
|
|
The sad part in all the comments on this topic is that not one suggested writing some documentation for the project. Documentation is always someone else's responsibility.
Two years ago I was handed 100KLOC of undocumented but production critical cowboy code. Programmer who wrote it was adamant that "the code is self documenting". It wasn't. It took 18 months to document it to the point where it could be maintained...barely. If you REALLY want to contribute to a project, write something other than code.
"Everyone complains about the weather, but no one does anything about it."
|
|
|
|
|
Documentation can be self documenting as well. The amount of times I despair when I see a summary of a method which basically repeats the method name.
Code should be simple and self explanatory as to the implementation. If it isn't then it probably needs to be refactored. A method can explain its function in its name, no need to repeat it (as an example I saw the documentation to an attribute "rtpHeaderExpected" as "expects an rtp header").
Documentation is useful when it explains the why of code, not the what (which is what the code should explain). So yes to documentation, but only when its useful !
|
|
|
|
|
|
It's admirable wanting to get involved and commit to an open source project, but my suggestion would be only get involved in a project if it's something you use/reference as part of some other development project you are working on, and there are improvements or fixes that would benefit your own project that you believe would also be of benefit to others.
|
|
|
|
|
Wastedtalent wrote: only get involved in a project if ...
I disagree. There is great value in studying large, commercial-grade software for its own sake. Even if the OP never commits but just spends hours or days spelunking one of the codebases he mentions, he is bound to be enriched by the process. Many of the techniques of enterprise-scale coding can't be taught in books.
|
|
|
|
|
I agree, I also think studying and getting involved in are two very different things, and the OP was talking about making commits.
|
|
|
|
|
I also suggest that getting involved in that depth with a project that you use regularly will increase your interest and commitment to the process.
Doing work on a project that you have little interest in, just for the sake of it, will soon feel like a thankless task.
I've only ever contributed to projects that I have a direct interest in, because the first step in contributing to any product is using it.
|
|
|
|
|
Do you know WHAT you want to contribute?
If you're just thinking about making some contribution or another you're going to have a difficult time, but if you have something specific in mind try to find just that place where it should be implemented.
For example, let's say your contribution is going to be that NodeJS always logs to the console when starting a server.
Now you want to find where it is that Node finds your file and runs it.
Since it's a command tool try looking for that point of entry, perhaps by searching for some optional parameters.
From there find where Node is loading your file, you can do this by following the code in your editor or debugger (I tend to use the debugger as I want to know for sure the code actually runs).
You should now be close to where you want to insert your code.
When working like that you can make contributions, add to the code, fix bugs, etc. without having to know everything that's going on.
I've never actually looked at the NodeJS code, let alone contribute to it, but that's what I would do.
P.S. Just for the record, my suggested contribution isn't exactly one we'd want (as we can optionally add it with a single line of code). It's just an example.
|
|
|
|
|
Go small at first.
Follow the code paths from UI to the finish line for that particular path. I cannot stress this technique enough. Pick a path that is relevant to your current task or project.
Don't try to learn the entire system at one time.
|
|
|
|
|
If a debugger is available, use it to see the call stack, for the functionality you're currently working on. This will give you an idea of the control flow for that functionality.
Once the first functionality is reasonably well understood, go to the next functionality, and so on.
|
|
|
|
|
Try reaching out to the dev community, and see if they can suggest easy items for a newcomer to the codebase. I know Mozilla has a list of them, but doubt they're the only project to do so.
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, waging all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
Training a telescope on one’s own belly button will only reveal lint. You like that? You go right on staring at it. I prefer looking at galaxies.
-- Sarah Hoyt
|
|
|
|
|
TheOnlyRealTodd wrote: when I open the project file for these, it can be tough trying to figure out where to even start.
Getting them to compile is the hardest step! 
TheOnlyRealTodd wrote: and also looking at the unit tests to get an idea of whats happening
That's a good approach, especially single stepping through the tests.
And write down everything you learn, and your questions for what you don't understand yet.
Personally, I think most of these open source sites could benefit greatly from writing some "programmer documentation", as you're not the only one with "how the elephant does this stuff work?" question. And that might be the most useful contribution at first!
Marc
|
|
|
|
|
Play with it without looking at the code, first -- get the grand view, and get to know the whys and wherefores.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
To analyse a large code base you could try running a dependency tool such as DeepEnds
|
|
|
|
|
|
The essence of your learning question is advice as to how you can most efficiently organize and sequence your code-reading-and-understanding learning tasks so as to attain a reasonable level of proficiency in the time you have allotted and at the same time reduce the time you will spend on the study of code without merit, which frankly is not possible until you have already learned it.
My suggestion is to, at the outset, refuse to learn and study code written in throw-away computer languages.
|
|
|
|
|
As always, working backwards is a good approach.
You can find previously FIXED Items, and review the posted code changes that fixed the item.
I would recommend being able to build/test the previous version, and verify the bug.
Apply the fix.
Verify the bug is gone.
If you get decent at that. Then get realistic. It takes approximately 5,000hrs to master a new skill.
Assuming you have mastered programming in general, lets assume a large code base will take you about 1,000hrs for a solid basic understanding. (Half a work year).
Yeah, it is easy to jump in and hack away. But actually mastering a code base.
This gets to the REASON others suggest you support a code base that you already use, like, and would like to extend.
BTW, as you setup your environment to test/validate prior updates. Considering reviewing and enhancing the documentation that helps others get to where you got to.
|
|
|
|
|
If you can find an issue that does not have a UnitTest, contribute a UnitTest that reproduces the issue.
|
|
|
|
|
I found the doxygen tool to be very helpful. I can show some call traces and is very convenient for navigating objects.
|
|
|
|
|
In GREP we trust. Use GREP, find in files, or find usages to see all the references to a particular class and it's public methods.
Start the new dev with a small task - a bug fix or minor enhancement. Then have the new dev document every class and method that contributes in some way to the scenario. Have the new dev document every other class and method that depends on the code that is changed, all the way up to the UI or interface.
Also, I absolutely concur with the idea of debugging and examining the stack. If unit tests and integration tests are available then run these in the debugger. If a developer went to the trouble to write unit tests, then it must be important.
|
|
|
|
|
Could I also echo the responses from some of the other repliers that that is a chronic shortage of documenters for most open source products?
They are like rocking horse poop.
If you want to hone your coding skills and can find a project that deeply interests you, then hack away.
If you are just looking to contribute to a project that matters to you, then documenters are always welcomed with open arms.
|
|
|
|
|
I think your first impulse (find and solve an issue) was the right one.
At least you have a "goal" in mind; the rest ("reading code") gets old pretty fast.
Ultimately, you will find out your value is in seeing the big picture quickly, and prioritizing what needs to be done.
A lot of code never gets executed or deals with fringe cases; better to focus on the stuff that actually gets run; i.e. the "buggy" parts.
|
|
|
|
|
Since you're a novice first focus on what you are comfy with.
Pick that layer.
Pick up a tool like Ndepend or Nitriq and see how the layers interact.
Then and only then start playing on the keyboard.
|
|
|
|
|
Here are a few tips.
If nothing else fix layout issues - indentation, spacing etc - and add (sensible) comments where it makes sense. The act of tidying up layout and having to think about what a small section of code is doing, in its own right, will help build your understanding of the bigger picture. From there is probably won't take long for you to start spotting refactoring opportunities.
If you do decide to make changes, start with the small trivial things since these will often be overlooked or tolerated for the sake of the big things. Build up a testing regime for your changes BEFORE you make the changes.
Don't focus on code structure or control too much. That will become obvious. The key to any code base is how it organizes its data and moves it around. This you can analyse and diagram.
Remember, fundamentally all any software is really about is moving data from A to B.
With this in mind, pay special attention to the interfaces between modules, components and systems. This is likely where the most problems are. Especially when either side of the interface has been independently developed.
Also look for places where data is transformed from one form to another e.g. conversions, lookups. Another source for faults.
If you are able to run the software, another way of gaining understanding is to include detailed logging/tracing of the software's operation as it is running. In this context, look to trace the initial state of variables and when variables change, the function calls (including explicit variable values) and function returns and error events in the code. Those three categories of logging should be enough for you to hone in on most problems with the code when it is running. This is ofc verbose and has performance implications so make sure it can be turned off or removed from the release product entirely.
Finally, study design patterns and identify where they have been used in the code. Either intentionally or unwittingly. You may be lucky and the patterns may be explicitly named e.g. WidgetFactory or WangleAdaptor. Design patterns are not the be all and end all, but they are a useful shorthand for common development problems.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
