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 want to ask about the different techniques they used to remember various programming techniques. We go through various books and various online tips and tutorials we also get so many ideas from the code written by somebody else.
Now all these inputs are memorized or stored in some format so that it can be found easily when referred. Absence of such storage may result in rewriting the code or reinventing the wheel.
I use to create one Working folder where I keep all my trial code but sometime after few days / months since the code is not tagged or named properly its difficult to find it out again.
For Perl, I have a module I call staging.pm, and use staging; is a pragma in my code which allows me to use experimental, not fully developed code in my development. This developmental code will be placed in a branch called "staging" off of the user library directory. The main thing that the module does is put my staging directory at the head of #INC. Once my code is mature--if it ever is--it will be moved into my user lib directory.
As for scripts, they can be run from wherever they are and I use a directory named test off of the bin directory.
So that's kind of my approach. I don't know how useful that is for you.
It's like learning any other language or learning any other technique. When you read a book and you find it interesting you start associating what you are reading with real life situations and problems that you might have had before which the new learnt stuff will solve for you.
You might, after a couple of days or so forget what you have learned, untill you stumble upon the problem which you related to when reading the book or looking at the lecture. This specific type of memory is called something like association memory technique.
There are a lot of other different techniques to remember things by but a lot of them come down to relationships with other parts of what you already know.
Another example is Math which is something you force your brain to understand but once you quit using it on a daily basis you will slowly degenerate the math-genious-cells.
Programming for me at least is just another way to express myself and when i learn new features it's just a new way to express things that might not have been easy to do before.
Edit
I might have missunderstood the question.. did i?
Well, for me, when I am trying to learn, I focus on learning the approach to solve the program, rather than a technique. That is important to me. Also, with regular day to day programming some techniques become ingrained.
The other thing I do is to maintain a notebook with my notes in it, code snippets, comments, shortcuts I have learnt over the years. This helps too.
Recently I have taken to maintaining my notes in Evernote, this makes is easy to search for and tag.
For web, I use Delicious + Firefox plugin to store what I already read.
When looking for a solution to something I can't solve, I got used to ask / search here.
And for my own solutions, I try to create reusable components and remember in which project I solved what and eventually get back to it later when I need it.
Whenever you study one programming technique like java you always map the corresponding things with C++ and perl.Java and C++ remain same in more concepts.And better you store your working folder in your mails so that whenever you need you can download and have it.
You could try a program like Surfulater. I don't know how well it works with code samples, but I do know that the developer was (is still?) active on the Joel on Software forums, so I'm sure he could be contacted with any specific questions.
If you use Windows, you can use Google Desktop to index part of your harddrive, including your program snippets.
If you can recall just some of it, Google will find it.
(Spotlight does the same automatically on a Mac)
On Mac OS X, TextMate provides a near perfect solution to this problem. TextMate is a programming editor that offers support for hundreds of programming languages and is customizable via the bundle editor. Through the bundle editor, you can add any snippet of code that you may want to memorize, and appropriately categorize it under its respective language. You can also assign hot-keys or character sequences to invoke a snippet and copy it to your current editing context.
I believe that Notepad++ is a similar tool for Windows, but I am unsure if it is as customizable as TextMate.
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 7 years ago.
Improve this question
I've been holding off on releasing a library I wrote because it is the first library which I'll be releasing publicly. Here are my concerns:
The library isn't complete it is in a very usable state, I'd say it is version 0.3, however it still lacks a number of features which I would like to at some point implement, and control how they're implemented (meaning not merging someones implementation).
I'm fearful of criticism, I know there are a few things which should be reorganized/refactored, but I wrote the initial class quickly to be functional for another project I am working on.
So when is the best time to release? Should I just throw it up on github and work on the issues post-release? Or should I wait until I refactor and feel completely comfortable with what I have written?
Most classes/libraries I see are always very elegantly written, however I have not seen any in very early release stages, are a lot of classes fairly sloppy upon initial release?
Release early, release often.
Criticism is a good thing as long as its constructive. Ignore the haters, pay attention to the folks filing bug reports and commenting.
The internal structure of the code matters, but it matters more if it works for its intended purpose. In general, refactoring will change how code works internally but will not affect how it is used. Same inputs and outputs.
You need to get something half-way
useful first, and then others will say
"hey, that almost works for me", and
they'll get involved in the project.
Linus Torvalds
Linux Times (2004-10-25).
It depends on why you are doing this. If it's to provide something useful and it's useful and has benefits that no other library has, then go for it. Just list the status and what's coming next.
If you are doing this to point to on a resume, get it in good shape (the code, not necessarily feature complete). Imagine a future employer poking around the code to see what it looks like, not downloading and running the code.
Whether you release the code in an incomplete state or not, it's always worthwhile having enough documentation to allow users to understand how to use the library.... even if it's only API docs. Make sure that anything incomplete is tagged as TO DO - it helps to maintain a target list of tasks to complete, and lets users know that the feature/method/whatever hasn't been forgotten.
Providing a set of code style/standard documents (perhaps with architectural notes on class relationships) allows other developers to contribute more readily, and in a manner that enhances the library rather than making it a hotch-potch of spaghetti code. It's never easy releasing a library, then having to refactor, while maintaining backward compatibility for users who have already taken up and are using that library in a production setting.
EDIT
Don't be afraid of criticism... it goes with the territory.
Some critcism can be constructive (take heed of that).
There'll be plenty of other people who criticise your code (for whatever their reason) without being constructive, or who just denegrate your work. The difference is, you've produced the goods, they probably haven't ever contributed to any OS product/library.
Users expect you to fix their problems immediately, or to write their code for them to use your library, or simply say "it doesn't work" without any explanation of what they mean. You have to learn to live with that 24x7x365.
But just once in a while, somebody will thank you for saving them hours of work, or for providing something useful... and suddenly all the stress and hassle feels worthwhile.
I read a document by Joshua Bloch, a pricipal software engineer at Google that talked a lot about the best type of API design. Basically, once you release it, it is more or less set. He says
Public APIs are forever - one chance to get it right
You can check out the slides here. It's definitely worth reading. I have a PDF of it as well; let me know if you need it.
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
Often there are situations where a project is passed on someone else. And often this process is unpleasant for both sides - the new owner complains about horrible documentation, bugs and bad design. The original owner is then bothered for months with questions about the project, requests to fix old bugs etc.
I might soon be in a situation where one of my projects will be given to someone else so I can focus on my other projects. I wonder what should I do to make this transfer as smooth as possible. What i already have is a decent documentation, the code is quite good commented and i'm still improving it. Its a medium sized project, not very large but still its not something you can code in a week.
I'm looking for a list of things that should be done in order to help the future owner taking over the project and at the same time will spare me all those annoying questions like "and what does this function do, what purpose does this class have...". I know documentation is a must - what else?
Note: although my project is in C++ i believe this is a language-agnostic question. If there are things you think are specific to some language, please mention them too.
Documentation is one thing, getting it into the head of your new project owner another. IMHO this is a typical situation where "less is more" - the less documentation your colleague has to read to understand something, the better. And, of course, learning takes time - for both of you, accept it.
So
instead of writing lots of documentation, make your code self-commentatory
have all documents / source code etc. in a clean and well named folder structure
make sure your build-process is almost completely automatic
don't forget to document your deployment process, if it is not automatic, too
clean-up, clean-up clean-up!
When taking over a project, documentation is of course desirable, but even more so is a good test suite. Trying to modify a program that you have no means of testing for correctness is a nightmare.
Documentation, but on all levels:
API docs
High level architecture: What components are there, what are their relationships and dependencies
For each component, a high level description pointing to important code sections
Tutorials: If you want to do X, here's how
Data: What data does it use and how, database schemas
Idioms: If you've created some idioms within your code, explain them
And, to start, give the guy a personal introduction to all of the above in person, hopefully doing some needed change in a pair programming way
the new owner complains about horrible documentation, bugs and bad design.
I suspect that no matter what you would do, new owner will always complain about something. People are different, so something that looks easy to understand for you, will look horrible and extremely complicated for someone else.
The original owner is then bothered for months with questions about the project, requests to fix old bugs etc.
In this case you should clearly refuse to help. If you won't refuse, you'll probably end up doing someone else's job for free. If maintaining the project is no longer your job, then the new guy should fix his problem without your help. If "the new guy" can't deal with that, he isn't suitable for the job and should quit.
Its a medium sized project,
"Medium sized" compared to what? How many lines or code, how many files, how many megabytes of code?
I wonder what should I do to make this transfer as smooth as possible. What i already have is a decent documentation, the code is quite good commented and i'm still improving it.
I would handle it like this:
First, do a sweep through the entire code and:
1.1 Remove all commented out blocks of code.
1.2 Remove all unused routines and classes (I'm talking about "forgotten" routines, not parts of utility library).
1.3 Make sure all code follow consistent formatting rules. I.e. you shouldn't mix class_a, ClassA and CClassA in same app, you shouldn't use different styles for putting brackets, etc.
1.4 Make sure that all names (class, variable, function) are self-explanatory. Your code should be as self-explaining as possible - this will save you from writing too much documentation.
1.5 In situations when there is a complicated or hard to understand function, write comments. Keep them as short as possible, and post only when they are absolutely necesarry.
1.6 Try to make sure that there are no known bugs left. If there are known bugs, document them and their behavior.
1.7 Remove garbage from project directories (files that are not used in project, etc.)
1.8 If possible, make sure that code still compiles and works as expected.
Generate html documentation with doxygen. Reveiw it few times, modify code comments a bit until you're satisfied. Or until you're somewhat satisfied with the result. Do not skip this step.
If there is a version control repository (say, git repository) with entire development history, hand it over to a new maintainer, or give him(her?) a functional copy of the repository. This will be useful for (git )bisecting and finding source of the bugs.
Once it is done, and code is transferred to a new maintainer, do not offer "free help", unless you're paid for it (or unless you get something else for helping, or unless it is order from your boss which makes helping new maintainer a part of your current task). Maintaining the code is no longer your job, and if new maintainer can't handle it, he isn't qualified for the job.
I think most of the problems can be avoided with just two simple rules.
Keep the code consistent with platform style guide.
Naming, naming and naming.
If the project is huge, then you just need to run some code camps with the new guys. There's no shortcut for this one.
Remember also that complaining happens mostly because new guy is not qualified enough, i.e. doesn't understand something. That's why it is important to keep things simple. And in case he is more qualified, then I guess you deserve it ;)
Some good advice where to start hacking/changing things is always better than documentation. Consider documentation as a backup material after you are familiar with the code, it should never be the starting point (except if you are exceptional technical writer with unlimited resources and time)
If there is good documentation and commented code as you say, then you've done your part. Just make sure that the documentation includes high-level documentation (architecture, data flow, etc.) as well as lower module or procedure-level documentation.
If this is a situation where you can, I would strongly suggest you protect yourself with some type of contract that specifies what future support (if any) you will provide and for how long.
I think for a situation like this the most important thing is a working, complete build that automatically compiles, documents, and tests the project. That way, there is a well defined point at which the new developer has it working. He can then figure stuff out from the tests and documentation, in principal.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
I have recently started working on some open source project which I found relevant to my interests.
During this initiation period I came across some terminologies/stuff that I am not acquainted with, like configure, tool chain, binutils, etc. which I agree depends upon the type of project you are working on.
Now my question is, are there some bare requirements a developer should know before starting to work on the project?
Any help/reference will be greatly appreciated.
EDIT:
I have seen the GNU configure and build system in most of the projects I have seen.
If someone bothers about it "The GNU configure and build system" is a good place to start.
If it's a pre-existing one, you'll need to read their development docs (if any), learn how to use their version control system, and have the requisite tools for building the code and running it.
If you have all that, and the knowledge of the code/language, then you just need enthusiasm and some spare time :)
I wouldn't define them as bare requirements in the sense that it appears you are looking for. If you're a programmer you already have (hopefully!) the self-learning and problem solving characteristics that probably led you to be a programmer at first.
You'll never really know 'everything', and will likely learn something new everywhere you go. Heck, I got my current job never even hearing the words "Model-View-Controller", but picked up the concept in no time.
Your examples, toolchain and binutils, are not complex concepts and a simple wiki article should suffice.
I'd suggest downloading all the source code and making sure you can build it yourself as a first step.
Try and make sure you are familiar with the overall design and documentation before attempting to make any changes to ensure you don't inadvertently break anything on your first change!
The terminologies being used will probably depend on the technologies being used, for example an open source project written in C++ and running on Linux, will likely be very different to a C#/.NET application build to run on Windows.
It depends on how much involvement you will get into. If you just want to contribute with a feature, just get the tools to build the project, an editor to change the file and enough doc reading to find injection point for your feature. If you can find someone to help you getting started it will be fairly easy.
If you are to be committed to the project I recommend learning build tools, project history and aims. Also how the current authors try to solve the problems, their perspective on the project will help.
I would say being able to understand all of the architecture, tools and technology for whatever project you're working on is a must.
However, you then tried to make this a generic question that applied to any open source project. You kind of answered that for yourself didn't you?
which I agree depends upon the type of
project you are working on
I would think that depends entirely upon the project. Most well set up software projects will specify:
What language(s) they're written in
What developer environments (if any) they're set up for
What tools you need to build/compile/run the project
Test data with which to test the software
What are you working on? Are you sure they don't provide any of this information?
It depends on what you qualify as "work" on the project.
Most of the answers here suggest that you're coding (and your question hinted in that direction), but there are things that you can do to contribute to projects -- like testing and documentation -- that can be done without knowledge of how the program's written.
Now, for the coding aspect of it -- if it's a smaller project, I'd try to figure out what the other contributor's motivation and grand plans/goals for the project are. As with any team, coming in and trying to take things in a completely different direction than the others are planning, even if you have good intentions, can cause all sorts of problems.
(and then there's the technical advice that everyone else said ... source control, build system, project architecture, toolkits used, etc.)
It depends, as you say, on the project.
You'll have to know how to work in the language, you'll have to be familiar with the source code control system they use (usually subversion). You'll have to be able to build (usually Ant, often Maven).
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 3 years ago.
Improve this question
I write hobby code from time to time. The thing is these tools, classes or tiny libraries of code end up in a flash stick with hopeless future! I would love to develop my projects further, and let other programmers trust them. If you were going to use something you found on the Internet, what is the most important thing you look for in that programming tool or small library? e.g. would you consider separate documentation a must?
Thanks for all contributers. I'll try my best to summarized what have been said. Feel free to modify the list. Corrections and additions are more that welcome :)
Start a blog and let others know you
are here.
Choose the most
suitable license. Possibly Open
Source licenses are the best for
hobby projects.
Put your project where people can
reach it. Consider google-code,
github, sourceforge or
other sites.
Use public version-control and
bug-tracker, So others can acquire the
latest source code of your project to
compile and use.
Write a decent documentation, beside
commenting your code clearly of
course. The documentation should
explain the purpose of the library
and provide at least simple examples.
Write tests if you are willing to provide real-world code.
If you are building a library, put a
lot of effort into designing a stable
interface.
Get a blog, release code through it. Explain why you wrote it, what problem it solves. And encourage others to improve upon it, keep the code posted as current as possible. If your tools are useful you will very quickly develop a following that 'trusts' your code.
Separate documentation isn't a must for small tools, but anything creeping into the framework world should probably have ample documentation and examples if you want any serious adoption from the community at large.
The most important thing is that the library is that it be open source, so I can read the code myself. If that is not possible then I insist on documentation.
Also consider using a project-hosting site (like google code or github).
Have a clear license with your code if you don't have one already
(preferably one which encourages modifying / improving / sharing your
code ...)
Have public version control and/or a public bug/issue tracker and/or a mailing list. There are a lot of good sites which offer these services for free.
Seperate documentation is not a deciding factor to me (if the code is well documented and the code quality is high).
Documentation explaining why you wrote it, when you started it, and it's intended function. Understanding where you're coming from will allow me to see future ideas as well as short coming you may not have seen.
Technical documentation explaining the API and some examples on how to implement it. Ideally, keep your documentation in the format that follows the language. For example C# tends to use the XML syntax for defining items. This allows me to feel at home when I'm reading it.
Clean code -- I can't stress this enough because far too many people write exceptionally ugly code. If you're code is ugly and/or unreadable, it may be easier for me to write it from scratch on my own. At the very least, make your code consistent. If I can't understand the code, I won't feel comfortable with it.
Historical records explaining your changes. Seeing how the project has grown allows me to plan better. It also allows people to see how you learn from your mistakes and get a sense of your skill level. Compared to a forum, you can get a feel for how fast things get fixed and then placed in to a new release.
Think long and hard on what kind of license you want there. Public domain? BSD? GPL? More restrictive?
A note on whether or not you mind being contacted and if there are any restrictions in this. For example, would you mind updates? Me explaining security holes? Or perhaps you might use a forum or wiki?
The ability for me to get your latest work and/or nightly builds. SVN or something. This is useful so I know if a bug I found is already fixed.
I think that documentation is a key point for your project.
The document must indicate:
what is the purpose of your library
what are the main features
a really short tutorial, to make it run in 5 minutes.
Many examples
I let people trust my code in a number of projects, but I urge people to make and maintain their own tests, and I make sure that I'm content with the unit tests.
Documentation is always good, but I'm very guilty of finding time to do as much as I would like. But having the author fairly contactable is helpful.
Posting it in an open source repository such as code.google.com or sourceforge.net is probably where to start...
Next to attract attention, document clearly and succintly the purpose of the library / application as outline in one of the answer above.
Finally, blogging and direct mail exchanges happen...
One reason documentation helps people trust your code, is that they know whether a given feature is something which you intended the code to do (and which you will, all else being equal, preserve in future versions of the code), or something that the current code just so happens to do, but which might change at any time as a side-effect of a bugfix or just a refactor.
Some people prefer find out what code really does by looking at it, and that's fine, but documentation tells you (a) what the code is supposed to do, and with any luck (b) what the next version of the code will do. If I want to use your code long-term, and take bugfix updates as you provide them, then I need to know that you've designed an interface that I can rely on and that you're willing to stick to. Documenting it is a strong hint that you're at least trying to do that.
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 find myself wanting to develop certain projects, but most of the time I lack motivation because I develop by myself.
What I usually do is look for similar existing projects, and ask the developers if they like to collaborate, but it's rather hard.
Is there a good place (a website maybe) to find people that are interested in the same project as me, and therefore would like to collaborate?
You code by yourself?
Release the code on one of the open-source foundries. (code.google.com. sf.net. bitbucket.org , github.com ,etc...)
Pick an easy license (x11/MIT is good, GPL2/3/AGPL3 if you like, among others.)
Write simple instructions on how to deploy, run, with a one-page tutorial.
Have a website where you write about the stuff you build, and the stuff you'd like to build.
Find people who need some help and help them. Don't over-extend yourself.
It takes time to build trust. Trust takes time.
Update
You wrote:
What I usually do is look for similar existing projects, and ask the developers if they like to collaborate, but it's rather hard.
If you see an open-source project out there, odds are the developers already like to collaborate. What they might not want to do is talk about grand schemes about how to turn the software into the next fifty billion-dollar behemoth. Generally, if you join the mailing list, introduce yourself ("Hi, I'm Joe, and I like to do X, and I like this software."), get and use the software, and provide feedback and constructive criticism, and demonstrate that you are following instructions or at least attempting to, and then, then, if you provide a patch (or a branch if github) it might be looked at and considered.
Do follow the project methodology. For example, if they use tests, submit tests with your patch, that sort of thing.
I tried myself to start an open source project and failed. I had published my idea in a forum and there were about 10 or 15 people who wanted to join the project. Actually there were very little activity ...
I think the main reason for the failure was that I hadn't developed anything before going public. It would have been really useful to have at least a prototype. Another thing is defining a (simple) development process.
If I would try it again, I would:
develop a prototype
document the code and the architecture in detail
write down tasks others could do
describe the development process
design a nice website and promote my work
publish the code at google code or something like that
Check out the offerings at github.com. If you can use git, I often find some cool projects on there, and you can always fork the repository to help out.
First, you should register your project on an Open Source Forge. There is a comparison list on Wikipedia : http://en.wikipedia.org/wiki/Comparison_of_open_source_software_hosting_facilities
On certain forges, there is a way to ask for help. I know that SourceForge does: https://sourceforge.net/people/
I recommend that you read Karl Fogel's excellent and complete book on the subject : Producing Open Source Software. It is freely available online or in print from Amazon.
If you already have some code somewhere online, you could put an ad for your project on Stack Overflow's Open Source Advertising.
Quote from the link:
It must be an advertisement soliciting the participation and
contribution of programmers writing actual source code. This is not
intended as a general purpose ad for consumer products which just
happen to be open source. It's for finding programmers who will help
contribute code or other programmery things (documentation, code
review, bug fixes, etc.).
Openhatch
is the best place I have found to look for open source projects