5 ms·

Teaching Software Architecture with GitHub

80 points by SanderMak 13y ago

n1ghtmare_ 13y ago
I'm finding it very difficult getting into a large open source project. I consider myself an experienced developer, but for some reason it feel very intimidating, especially when the code base is large. I was wondering if someone could give any tips ?
- yeukhon 13y ago
  I try to work on the software I actually use. I don't jump on a random horse and start riding to the West. I think the first step is look at your tools. What problem do you have with your tools. Is the library you using too restricted? Does it have a null/nonetype exception rasied and not properly handle? If you can't solve it because you have no idea where to start, well, at least file a ticket :) I have limited experience too. I think the first real contribution was Ansible, rewriting the hg module was critical for my use. So I did. When I was an intern at Mozilla I learned about CSP so later when I found a few minor issues with the CSP implementation in Firefox I started volunteering. My internship didn't involve a single line of writing Firefox code so it did take a while to navigate through a couple files for a newbie. But grep, mxr.mozilla.org all helped. I think even just making demos and making documentation changes is equally powerful and useful contribution.
  - n1ghtmare_ 13y ago
    Awesome! This is actually quite helpful and it gave me a couple of ideas.
- avandeursen 13y ago
  The students of the course had the same problem. We advised the students to look critically at recent open (or just closed) issues and pull requests, as well as e.g., the mailing list for the project at hand. Based on that they could get a feeling what was happening at the moment, and what a typical contribution looks like. If you want to contribute code, we found that it works best if you work on parts of the code that are currently under active development. This also means that you do not have to have a deep understanding of the full code base: A broad overview suffices. Some of our students also offered documentation for, e.g., installation or deployment: they struggled themselves, and offered what they learned back to the project.
  - n1ghtmare_ 13y ago
    Thanks for the answer, it helps a lot !
jimicy 13y ago
Wow I wish my university offered courses like this. As a student what are good books for software engineering practices in the field right now? Also when you're doing sole projects are there specific procedures you should follow and how do they differ from when you're in a team? Lastly if it isn't too much can you post links to the course website for this,the software communications and software metrics?
- yeukhon 13y ago
  > good books for software engineering practices in the field right now I think there is none. I think every organization is different. The best thing to do is be communicative, responsive and honest. Moving agile means all the above. Rule one is start small and go simple. Just spent three days on making something and I got stuck so I said fuck it, start small. So I need to build this tool that reads the output of another tool. Sadly it comes out in terminal with all kinds of custom format. Instead of parsing the full "terminal output" I receive, I start small by reading and getting whatever I need. Gradually I built up the "reader/parser" I need to from this report I was trying to parse. And I finished what I was hoping to finish. > Also when you're doing sole projects are there specific procedures you should follow and how do they differ from when you're in a team? It's very subjective. I think if you are accustom to one way you do it that way more often. But I said in my example, I spent three days trying to go complex. That's the failure of me, but it probably happen to everyone everytime because I (or we) think I was smart so I could solve this complex issue. The only rule I have when I do sole project is to define the scope of my project. I write down whatever I want to implement, what it does. Essentially building up a set of user stories for myself. But that's also true for team project. You just can't be sloppy and acting alone when you do team work... so when you work with others, get the user stories up and running, figure out the style you want to code in... they all matter. Last thing: it's easy to say, but it is damn hard to do it. Just relax.
- jonaspf 13y ago
  Personally I think this is a good starting point: http://gorban.org/post/32873465932/software-architecture-cheat-sheet http://gorban.org/post/32873465932/software-architecture-che... In terms of books, I really like "The Architecture of Open Source Applications" (http://aosabook.org/ http://aosabook.org/) which is also mentioned in the blog post. For the enterprise world, "Patterns of Enterprise Application Architecture" (http://martinfowler.com/books/eaa.html http://martinfowler.com/books/eaa.html) is a good choice. However, before applying any technical software architecture methods, it is really important to understand what your stakeholders actually want/need. Unfortunately most of the time they don't even know it themselves. In my experience most software projects fail, not because of technical reasons but simply because the original problem hasn't been understood. This is where communication is key. I assume the reason why the authors of the blog post encouraged drawing diagrams and looking at different perspectives/views is to facilitate this communication.
stiff 13y ago
It is actively harmful to teach students that software architecture is something that somehow arises from diagrams or that those kinds of silly pictures capture anything important about it. Powerful architectures come out of powerful ideas that in turn come from accumulated hard work of many people in different disciplines. One can learn much more from walking through the actual source code of some classic projects and from trying to understand the ideas that make them tick: https://github.com/onetrueawk/awk https://github.com/onetrueawk/awk - UNIX philosophy of small tools, DSLs, CS theory: state machines / regular expressions, Thompson algorithm ... https://github.com/mirrors/emacs https://github.com/mirrors/emacs - Both a program and a VM for a programming language, hooks, before/after/around advices, modes, asynchronous processing with callbacks, ... Worth to think of challenges of designing interactive programs for extensibility. https://github.com/rails/rails https://github.com/rails/rails - Metaprogramming DSLs for creating powerful libraries, again a lesson in hooks (before_save etc.), advices (around_filter etc.), ... https://github.com/git/git https://github.com/git/git - The distributed paradigm, lots of CS theory again: hashing for ensuring consistency, DAGs everywhere, ... By the way, the sentence "yet the underlying git magic sometimes resulted in frustration with the students" is hilarious in the context of a "software architecture" course. One of computer algebra systems - the idea of a http://en.wikipedia.org/wiki/Canonical_form http://en.wikipedia.org/wiki/Canonical_form One of computer graphics engines - Linear algebra ... There are loads of things one can learn from those projects by studying the source in some depth, but I can't think of any valuable things one could learn by just drawing pictures of the modules and connecting them with arrows. There are also several great books that explore real software design issues and not that kind of pretentious BS, they all come from acknowledged all-time master software "architects", yet all of them almost never find diagrams or "viewpoints" useful for saying the things they want to say, and they all walk you through real issues in real programs: http://www.amazon.com/Programming-Addison-Wesley-Professional-Computng-Series/dp/0131429019 http://www.amazon.com/Programming-Addison-Wesley-Professiona... http://www.amazon.com/Paradigms-Artificial-Intelligence-Programming-Studies/dp/1558601910/ http://www.amazon.com/Paradigms-Artificial-Intelligence-Prog... http://www.amazon.com/Structure-Interpretation-Computer-Programs-Engineering/dp/0262510871 http://www.amazon.com/Structure-Interpretation-Computer-Prog... http://www.amazon.com/Unix-Programming-Environment-Prentice-Hall-Software/dp/013937681X http://www.amazon.com/Unix-Programming-Environment-Prentice-... http://www.amazon.com/Programming-Environment-Addison-Wesley-Professional-Computing/dp/0321637739/ http://www.amazon.com/Programming-Environment-Addison-Wesley... To me, the kind of approach pictured in the post, seems like copying methods from electrical or civil engineering to appear more "serious", without giving due consideration to whether they really are helpful for anything for real-world software engineering or not. The "software engineering" class which taught those kind of diagram-drawing was about the only university class I did not ever get any use from, in fact I had enough industry experience by the point I took it that it just looked silly.
programminggeek 13y ago
I guess this is s good approach to expose students to various software architectures and what real projects end up looking like. However, I'm not sure that this teaches the students what good architecture is/does and how it evolves over time. Which is to say, I'm not sure that this explanation says that the course teaches students how to DO good software architecture. Knowing about architecture and doing it in your own code are two different things.
davidradcliffe 13y ago
What a great opportunity for these students. I wish my university had done something like this.

80 points by SanderMak 13y ago

I'm finding it very difficult getting into a large open source project. I consider myself an experienced developer, but for some reason it feel very intimidating, especially when the code base is large. I was wondering if someone could give any tips ?

yeukhon 13y ago
I try to work on the software I actually use. I don't jump on a random horse and start riding to the West. I think the first step is look at your tools. What problem do you have with your tools. Is the library you using too restricted? Does it have a null/nonetype exception rasied and not properly handle? If you can't solve it because you have no idea where to start, well, at least file a ticket :) I have limited experience too. I think the first real contribution was Ansible, rewriting the hg module was critical for my use. So I did. When I was an intern at Mozilla I learned about CSP so later when I found a few minor issues with the CSP implementation in Firefox I started volunteering. My internship didn't involve a single line of writing Firefox code so it did take a while to navigate through a couple files for a newbie. But grep, mxr.mozilla.org all helped. I think even just making demos and making documentation changes is equally powerful and useful contribution.
- n1ghtmare_ 13y ago
  Awesome! This is actually quite helpful and it gave me a couple of ideas.
avandeursen 13y ago
The students of the course had the same problem. We advised the students to look critically at recent open (or just closed) issues and pull requests, as well as e.g., the mailing list for the project at hand. Based on that they could get a feeling what was happening at the moment, and what a typical contribution looks like. If you want to contribute code, we found that it works best if you work on parts of the code that are currently under active development. This also means that you do not have to have a deep understanding of the full code base: A broad overview suffices. Some of our students also offered documentation for, e.g., installation or deployment: they struggled themselves, and offered what they learned back to the project.
- n1ghtmare_ 13y ago
  Thanks for the answer, it helps a lot !

jimicy 13y ago

Wow I wish my university offered courses like this. As a student what are good books for software engineering practices in the field right now? Also when you're doing sole projects are there specific procedures you should follow and how do they differ from when you're in a team? Lastly if it isn't too much can you post links to the course website for this,the software communications and software metrics?

yeukhon 13y ago
> good books for software engineering practices in the field right now I think there is none. I think every organization is different. The best thing to do is be communicative, responsive and honest. Moving agile means all the above. Rule one is start small and go simple. Just spent three days on making something and I got stuck so I said fuck it, start small. So I need to build this tool that reads the output of another tool. Sadly it comes out in terminal with all kinds of custom format. Instead of parsing the full "terminal output" I receive, I start small by reading and getting whatever I need. Gradually I built up the "reader/parser" I need to from this report I was trying to parse. And I finished what I was hoping to finish. > Also when you're doing sole projects are there specific procedures you should follow and how do they differ from when you're in a team? It's very subjective. I think if you are accustom to one way you do it that way more often. But I said in my example, I spent three days trying to go complex. That's the failure of me, but it probably happen to everyone everytime because I (or we) think I was smart so I could solve this complex issue. The only rule I have when I do sole project is to define the scope of my project. I write down whatever I want to implement, what it does. Essentially building up a set of user stories for myself. But that's also true for team project. You just can't be sloppy and acting alone when you do team work... so when you work with others, get the user stories up and running, figure out the style you want to code in... they all matter. Last thing: it's easy to say, but it is damn hard to do it. Just relax.
jonaspf 13y ago
Personally I think this is a good starting point: http://gorban.org/post/32873465932/software-architecture-cheat-sheet http://gorban.org/post/32873465932/software-architecture-che... In terms of books, I really like "The Architecture of Open Source Applications" (http://aosabook.org/ http://aosabook.org/) which is also mentioned in the blog post. For the enterprise world, "Patterns of Enterprise Application Architecture" (http://martinfowler.com/books/eaa.html http://martinfowler.com/books/eaa.html) is a good choice. However, before applying any technical software architecture methods, it is really important to understand what your stakeholders actually want/need. Unfortunately most of the time they don't even know it themselves. In my experience most software projects fail, not because of technical reasons but simply because the original problem hasn't been understood. This is where communication is key. I assume the reason why the authors of the blog post encouraged drawing diagrams and looking at different perspectives/views is to facilitate this communication.

stiff 13y ago

It is actively harmful to teach students that software architecture is something that somehow arises from diagrams or that those kinds of silly pictures capture anything important about it. Powerful architectures come out of powerful ideas that in turn come from accumulated hard work of many people in different disciplines. One can learn much more from walking through the actual source code of some classic projects and from trying to understand the ideas that make them tick: https://github.com/onetrueawk/awk https://github.com/onetrueawk/awk - UNIX philosophy of small tools, DSLs, CS theory: state machines / regular expressions, Thompson algorithm ... https://github.com/mirrors/emacs https://github.com/mirrors/emacs - Both a program and a VM for a programming language, hooks, before/after/around advices, modes, asynchronous processing with callbacks, ... Worth to think of challenges of designing interactive programs for extensibility. https://github.com/rails/rails https://github.com/rails/rails - Metaprogramming DSLs for creating powerful libraries, again a lesson in hooks (before_save etc.), advices (around_filter etc.), ... https://github.com/git/git https://github.com/git/git - The distributed paradigm, lots of CS theory again: hashing for ensuring consistency, DAGs everywhere, ... By the way, the sentence "yet the underlying git magic sometimes resulted in frustration with the students" is hilarious in the context of a "software architecture" course. One of computer algebra systems - the idea of a http://en.wikipedia.org/wiki/Canonical_form http://en.wikipedia.org/wiki/Canonical_form One of computer graphics engines - Linear algebra ... There are loads of things one can learn from those projects by studying the source in some depth, but I can't think of any valuable things one could learn by just drawing pictures of the modules and connecting them with arrows. There are also several great books that explore real software design issues and not that kind of pretentious BS, they all come from acknowledged all-time master software "architects", yet all of them almost never find diagrams or "viewpoints" useful for saying the things they want to say, and they all walk you through real issues in real programs: http://www.amazon.com/Programming-Addison-Wesley-Professional-Computng-Series/dp/0131429019 http://www.amazon.com/Programming-Addison-Wesley-Professiona... http://www.amazon.com/Paradigms-Artificial-Intelligence-Programming-Studies/dp/1558601910/ http://www.amazon.com/Paradigms-Artificial-Intelligence-Prog... http://www.amazon.com/Structure-Interpretation-Computer-Programs-Engineering/dp/0262510871 http://www.amazon.com/Structure-Interpretation-Computer-Prog... http://www.amazon.com/Unix-Programming-Environment-Prentice-Hall-Software/dp/013937681X http://www.amazon.com/Unix-Programming-Environment-Prentice-... http://www.amazon.com/Programming-Environment-Addison-Wesley-Professional-Computing/dp/0321637739/ http://www.amazon.com/Programming-Environment-Addison-Wesley... To me, the kind of approach pictured in the post, seems like copying methods from electrical or civil engineering to appear more "serious", without giving due consideration to whether they really are helpful for anything for real-world software engineering or not. The "software engineering" class which taught those kind of diagram-drawing was about the only university class I did not ever get any use from, in fact I had enough industry experience by the point I took it that it just looked silly.

programminggeek 13y ago

I guess this is s good approach to expose students to various software architectures and what real projects end up looking like. However, I'm not sure that this teaches the students what good architecture is/does and how it evolves over time. Which is to say, I'm not sure that this explanation says that the course teaches students how to DO good software architecture. Knowing about architecture and doing it in your own code are two different things.

davidradcliffe 13y ago

What a great opportunity for these students. I wish my university had done something like this.