To what extent should I design an open-source project before any code?

[octopod]

when making solo github projects, i tend to code from my head rather than from something i designed beforehand. now since this next project will likely be worked on by multiple people, i figure it would be good to design the project a little bit before starting it. that is, for example for a c++ project, what the classes should be, what methods there are, etc.

i have no idea how people usually design github projects, so i looked at some popular repos to see how they would design, but so far i haven't seen a single repo, even big ones like OBS or dolphin, that does (some of them have documentation, but usually they're generated from the code that's already made). so i'm thinking that these projects have either started without a solid design, or has had a design but the doc for it is private for some reason.

so i guess i have two questions:

- to what extent should an open-source project be designed (if at all)?

- if i should design it, is there a standard way of designing the software if it's on something like GitHub (like UML or something, but do I just push those documents to the code?)

apologies in advance if it seems like a stupid question.

[cheesylard]

i wouldnt worry about it too much, that kinda stuff only really matters if you're as big as dolphin or something

[Megalan]

This is more generic design tip than open source design tip but still worth mentioning: Think if your app will benefit from using a plugin system. Because you could end up in the same situation as ShareX where there is a lot of useless stuff (to the most people) in the app itself and the only way to make it modular is to rewrite most of it from scratch.

[brianosaur]

[QUOTE=Octopod;51255678]when making solo github projects, i tend to code from my head rather than from something i designed beforehand. now since this next project will likely be worked on by multiple people, i figure it would be good to design the project a little bit before starting it. that is, for example for a c++ project, what the classes should be, what methods there are, etc.

i have no idea how people usually design github projects, so i looked at some popular repos to see how they would design, but so far i haven't seen a single repo, even big ones like OBS or dolphin, that does (some of them have documentation, but usually they're generated from the code that's already made). so i'm thinking that these projects have either started without a solid design, or has had a design but the doc for it is private for some reason.

so i guess i have two questions:

- to what extent should an open-source project be designed (if at all)?

- if i should design it, is there a standard way of designing the software if it's on something like GitHub (like UML or something, but do I just push those documents to the code?)

apologies in advance if it seems like a stupid question.[/QUOTE]

The design should come naturally honestly. The design of your program can come from a combinaion your general workflow and how you code.

I would do the simplest thing that gets a feature to work, and as you keep adding functionality you will be forced to make some sort of abstraction by usually implementing a software design pattern or a variation of one that fits your needs.

I'm sure you have heard of TDD, often known as Test Driven Development or even Test Driven Design. Because by simply testing your code you will have an impact on the way its designed. Try it :)

But to answer your question, engineers do not spend hours coming up with designs for the code, at least the people who do agile. There may be a short ~30min whiteboard design session which are valuable if done right.

[Fourier]

Whatever you do, include some good documentation (outside code and inside code) or there is chance that no-one will even smell your project.

[octopod]

[QUOTE=Fourier;51257805]Whatever you do, include some good documentation (outside code and inside code) or there is chance that no-one will even smell your project.[/QUOTE]

yes, of course. i was just concerned that different developers might have different directions in mind regarding the design of the project since i myself don't know for sure and haven't written it down, which might in turn cause conflicts down the line.

but if it isn't as bad as i'm making it out to be then i don't mind having the design come "naturally". the documentation will always come either way.

[editline]25th October 2016[/editline]

[QUOTE=brianosaur;51257711]But to answer your question, engineers do not spend hours coming up with designs for the code, at least the people who do agile. There may be a short ~30min whiteboard design session which are valuable if done right.[/QUOTE]

if i did design it on a whiteboard, is there a standard way of doing it and if there is, somewhere i can read to learn more about that?

[brianosaur]

It depends. I see whiteboard sessions as a way to communicate your code through designs with your teammates. Or it might help you flesh out that idea you have going on in your head. I don't think there's an exact science to it, but you can use a formal UML diagrams, or boxes with text with arrows to other boxes and text. It depends on how high level you are talking.. Are you trying to show relationships between classes, communication between servers/services, or sequence of method calls for a certain feature to work? That effects the type of drawing you might do. But in the end all that matters is that you communicate the idea effectively