Re: [PHP] Joining a team, where no wiki or docs are available
I know this is a bit of an old topic, but I feel really strongly about this type of thing, as it's been a source of a *lot* of frustration over the years, and took me a long time to figure out something that works well for me. Some of the stuff below has been mentioned by other people, but I think a few things deserve further extrapolation. I hope you, and others, find the following useful. AmirBehzad Eslami writes: > Hi, > > i'm going to join a mid-size company with a few PHP-driven projects > written in procedural PHP, million years old. Oooh, I've been in that boat more times than I'd care to admit. > At the moment, they don't have a wiki or any documentation about their > projects. For me, the first challenge in probation period is to understand > how their code works. If there's one thing I've learned in my adventures at PHP shops with old crumbly codebases, it's that the wiki and docs are *wrong* anyhow. You *have* to understand the *code*, and you *have* to ensure that you have an understanding of the code. In ideal circumstances, it's tough to learn how to grok existing codebases. In *this* type of circumstance it can feel damn near impossible. > Considering that there is no wiki or docs, How can I see the Big Picture?* > i'm sure this is a common problem for programmers everywhere. > > What approach do you use in a similar situation? > Is there a systematic approach for this? > Is there reverse-engineering technique to understand the design of code? > > Please share your experience and thoughts. Well, there's a "very big picture", which relates to conceptual paths of action with particular intent through the software, and relates less to code and more to conceptual application design -- you get this by knowing what the software is for, and talking to the people who are creating it and using it, and understanding what they're trying to do. The rest of this reply is going to be focusing on the "Big Picture" as it pertains to understanding the code you're working on, particularly because you mention that you're doing a "refactor". Refactors without certain types of rigor often fail. Hard. Due to lack of understanding of the "Big Picture" of the codebase being worked on, and due to lack of separation of concern in the existing codebase. Subtle lack of separation of concern. Drive-you-insane subtle. I can't stress this enough -- it sounds like you are going down a path that I, and many other much more competent devs, have been down too many times. It's a path that *seems* simple, certainly simpler than the shit I'm about to talk about, but that's because you don't know what you don't know. You need to know that to know the Big Picture. You must know that you don't know what you don't know. You *must* learn to have this as part of your active mindset when dealing with "legacy" deployed codebases. The approach you need to take is different than it is when starting fresh. The "Big Picture", and your understanding of it, is an emergent property of the functionality of the existing codebase and your understanding of the parts that make up that functionality. Let's get to it: First, if they aren't already, get things into version control. A dvcs. Even if it's just your local copy, and you have to do silly things like tell svn to ignore ".git" and tell git to ignore ".svn" dirs because git-svn won't work with this codebase. I prefer git. I prefer git because it focuses on allowing you to manipulate and get information about the DAG that represents the various changes you've made and its nodes. It's invaluable for getting a codebase back to some amorphous time between then and now when things worked but there's maybe been a bunch of stuff that happened and something previously unnoticed is broken. That said, any dvcs will do, but seriously you need to be able to track changes for yourself and yourself only while poking around, and you need to be able to revert them or keep them as needed. Second, xdebug. Get familiar with it. xhprof. get familiar with it. Get familiar with the options they have for generating profiling and execution traces. Turn them on, do something really simple like "load the homepage", and then start looking a bit at what's going on. Any programming environment worth its salt will let you take an execution trace and follow it around in your editor. I use Emacs. I do use geben occasionally, but I don't do much step debugging. Try to understand at least a bit of the surrounding code at each point in the trace. Don't bother trying to understand all of it at once, there's too much (I've worked on PHP codebases that could produce multiple-gig execution traces on a page load when the verbosity of the trace was high. I hope you and everyone else never have to work on them). Doing this gives you a little bit of a feel for typical paths of execution, and exposes you to a fair amount of existing code. Now for the absolute most important thing to do here: Do *not* refactor
Re: [PHP] Joining a team, where no wiki or docs are available
Wow. David. That was a great help with every detail ! Thanks for sharing that with us. One side question: Without OOP, how do you handle Unit Tests? Do you know a Testing framework for procedural code?
Re: [PHP] Joining a team, where no wiki or docs are available
AmirBehzad Eslami hat am 24. September 2012 um 16:05 geschrieben: > What approach do you use in a similar situation? > Is there a systematic approach for this? > Is there reverse-engineering technique to understand the design of code? Hi Amir, my first start in such situations is -> phpDocumentor or anything like that -> xdebug + Cachegrind This way + a few requests and you'll get with the help of the profiling logs a good overview about the code and where the data flows. When you now browse the code, make sure you'll put comments everywhere you go and setup the wiki for yourself to document any kind of workflow you find. Marco Behnke Dipl. Informatiker (FH), SAE Audio Engineer Diploma Zend Certified Engineer PHP 5.3 Tel.: 0174 / 9722336 e-Mail: ma...@behnke.biz Softwaretechnik Behnke Heinrich-Heine-Str. 7D 21218 Seevetal http://www.behnke.biz -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP] Joining a team, where no wiki or docs are available
On Mon, Sep 24, 2012 at 5:07 PM, Daevid Vincent wrote: > That is a good point. We do not do unit tests here. Nothing against them, > it’s just a bit overkill for our needs. We build lots of websites, not one > massive SaaS. > > But I’m not saying do not use OOP. I’m just saying not everything has to be > OOP. It’s a subtle but significant difference. > We have OOP classes for our database connection (and of course the helper > routines), memecache access/purging/etc., and then objects for actors, > movies, scenes, search results, HTML templates, email, tickets, etc… again, > use the right tool for the job. When all you have is a hammer, everything is > a nail. Build a toolbox. ;-) > > From: AmirBehzad Eslami [mailto:behzad.esl...@gmail.com] > Sent: Monday, September 24, 2012 12:47 PM > To: Daevid Vincent > Cc: PHP General Mailing List > Subject: Re: [PHP] Joining a team, where no wiki or docs are available > > Wow. David. That was a great help with every detail ! > Thanks for sharing that with us. > > One side question: > Without OOP, how do you handle Unit Tests? > Do you know a Testing framework for procedural code? Wait, what? Unit testing has been around longer than OOP There weren't the nifty frameworks that make unit testing classes so much fun today, but you know you can *still* use them on procedural code. -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
RE: [PHP] Joining a team, where no wiki or docs are available
That is a good point. We do not do unit tests here. Nothing against them, it’s just a bit overkill for our needs. We build lots of websites, not one massive SaaS. But I’m not saying do not use OOP. I’m just saying not everything has to be OOP. It’s a subtle but significant difference. We have OOP classes for our database connection (and of course the helper routines), memecache access/purging/etc., and then objects for actors, movies, scenes, search results, HTML templates, email, tickets, etc… again, use the right tool for the job. When all you have is a hammer, everything is a nail. Build a toolbox. ;-) From: AmirBehzad Eslami [mailto:behzad.esl...@gmail.com] Sent: Monday, September 24, 2012 12:47 PM To: Daevid Vincent Cc: PHP General Mailing List Subject: Re: [PHP] Joining a team, where no wiki or docs are available Wow. David. That was a great help with every detail ! Thanks for sharing that with us. One side question: Without OOP, how do you handle Unit Tests? Do you know a Testing framework for procedural code?
Re: [PHP] Joining a team, where no wiki or docs are available
On Mon, Sep 24, 2012 at 3:06 PM, Daevid Vincent wrote: > > And for the love of [insert deity of your choice here] not EVERYTHING has > to be OOP. Use the best tool for the job!! Nothing pisses me off more than > having to instantiate a new class just to do some simple method that a > standard function would do. If you want to be organized, use static methods > then where appropriate, but don't avoid functions just because some book > told you that OOP is the king $hit. > > I'll never forget my first experience with a full blown Zend framework application. There were about 13 files and around 15k lines of code included to display one line of text in the header where just a simple echo would have sufficed.
RE: [PHP] Joining a team, where no wiki or docs are available
> -Original Message- > From: AmirBehzad Eslami [mailto:behzad.esl...@gmail.com] > Sent: Monday, September 24, 2012 7:05 AM > To: PHP General Mailing List > Subject: [PHP] Joining a team, where no wiki or docs are available > > Hi, > > i'm going to join a mid-size company with a few PHP-driven projects > written in procedural PHP, million years old. > > At the moment, they don't have a wiki or any documentation about their > projects. For me, the first challenge in probation period is to understand > how their code works. > * > Considering that there is no wiki or docs, How can I see the Big Picture?* > i'm sure this is a common problem for programmers everywhere. > > What approach do you use in a similar situation? > Is there a systematic approach for this? > Is there reverse-engineering technique to understand the design of code? > > Please share your experience and thoughts. > > -Thanks in advance, > Behzad I was in this same situation when I started 2011-03. No wiki. No revision control. No real process. No documentation. They'd push to production by copying files manually. When they wanted to create a new website, they'd clone an existing one and start modifying -- no shared libraries (so they had 50 versions of the same dbconnection.class.php but all just slightly different since that is also where they housed the configuration user/pass/etc.)!! It was a clu$terfsck. Take a day or two to go through every menu item and just see how the thing works from a user POV. You don't have to memorize it, just be familiar with concepts, vocabulary, paths, etc. First thing I did was install Trac http://trac.edgewall.org/ And of course Subversion. I personally recommend the 1.6 branch and not the newer 1.7 that uses sqlite. That version seems to always corrupt, especially on the clients (like in TortoiseSVN). http://subversion.apache.org/ I would use something to visually map out the database. If it's using MySQL, there are free tools like MySQL Workbench. But if they don't use InnoDB tables, it can get painful to draw the lines if it's a large DB. http://www.mysql.com/products/workbench/ I then started to go through code and use PHPDoc for every major function or method, especially in classes or include files where the meaty stuff happens, or very complex portions. I didn't bother with every get_* or set_* unless there was something obscure about them. Although, over a year later, and we have pretty much filled them all in now as the other devs started helping once they saw how easy it is to do a few as you encounter them in your daily coding, and how awesome that integrates with PDT or Zend Studio (amongst other IDEs). We didn't generate an actual PHPDoc Web version, there's really no need. The IDE shows you the important stuff anyways. We're pretty diligent about keeping these PHPDoc comment blocks updated now. http://www.zend.com/en/products/studio/ I then started the long tedious process of merging our various different sites to implement shared libraries (database connections, memecache, various objects, etc.). If you have only one project, then this is less of an issue, but if you have > 1 vhost or something then you'll want to do this. All the while I documented useful tips, tricks, explanations, etc. in the Wiki. Referencing source code (which is of course committed at this point). Trac rules in that respect. Xdebug will give you vastly better call stack and var_dump() alone. I don't use the breakpoint stuff myself, but that is another benefit perhaps. http://xdebug.org/ And for the love of [insert deity of your choice here] not EVERYTHING has to be OOP. Use the best tool for the job!! Nothing pisses me off more than having to instantiate a new class just to do some simple method that a standard function would do. If you want to be organized, use static methods then where appropriate, but don't avoid functions just because some book told you that OOP is the king $hit. d -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP] Joining a team, where no wiki or docs are available
On Mon, Sep 24, 2012 at 9:09 PM, AmirBehzad Eslami wrote: > Shiplu, > For debugging, what else do you use beyond xdebug and var_dump() ? Netbeans for PHP and Eclipse PDT. Both has good debugger support. An all-in-one package will server your purpose. Otherwise configuring xdebug might be painful. -- Shiplu.Mokadd.im ImgSign.com | A dynamic signature machine Innovation distinguishes between follower and leader
Re: [PHP] Joining a team, where no wiki or docs are available
Shiplu, For debugging, what else do you use beyond xdebug and var_dump() ? On Mon, Sep 24, 2012 at 6:07 PM, shiplu wrote: > If there is no wiki there could be inline comment. If not inline comments > and those are written by your peers, dont join that team. > Even there are inline comments you'll need to understand the architecture > fast. Inline comments will help to understand a small context but not the > whole > For this try run the application with a debugger. And step through it. If > you know debugging well in PHP you'll understand the workflow. > > -- > Shiplu.Mokadd.im > ImgSign.com | A dynamic signature machine > Innovation distinguishes between follower and leader > >
Re: [PHP] Joining a team, where no wiki or docs are available
+Like. The idea of mapping the db-structure and logic behind each page is interesting. Thanks for sharing. On Mon, Sep 24, 2012 at 6:06 PM, admin wrote: > > > I would start by mapping their databases structure. > Now for each page I would map out any functions, statements or includes to > a diagram and documenting explanations for everything. > > This will allow you to see pitfalls, bad coding, and areas of improvement. > This will also allow you do explain to them what the application really > does. > Think documentum > > > > > > > -- Kind regards, -behzad
Re: [PHP] Joining a team, where no wiki or docs are available
If there is no wiki there could be inline comment. If not inline comments and those are written by your peers, dont join that team. Even there are inline comments you'll need to understand the architecture fast. Inline comments will help to understand a small context but not the whole For this try run the application with a debugger. And step through it. If you know debugging well in PHP you'll understand the workflow. -- Shiplu.Mokadd.im ImgSign.com | A dynamic signature machine Innovation distinguishes between follower and leader
RE: [PHP] Joining a team, where no wiki or docs are available
> -Original Message- > Hi, > > i'm going to join a mid-size company with a few PHP-driven projects written > in procedural PHP, million years old. > > At the moment, they don't have a wiki or any documentation about their > projects. For me, the first challenge in probation period is to understand > how their code works. > * > Considering that there is no wiki or docs, How can I see the Big Picture?* > i'm sure this is a common problem for programmers everywhere. > > What approach do you use in a similar situation? > Is there a systematic approach for this? > Is there reverse-engineering technique to understand the design of code? > > Please share your experience and thoughts. > > -Thanks in advance, > Behzad Behzad, I would start by mapping their databases structure. Get an understanding of the data behind the application. Normally this gives you a better insight into their thought process, providing they use one. Now for each page I would map out any functions, statements or includes to a diagram and documenting explanations for everything. Because their concept of what the application does may not be the actual functionality. This will allow you to see pitfalls, bad coding, and areas of improvement. This will also allow you do explain to them what the application really does. Think documentum -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP] Joining a team, where no wiki or docs are available
I would first start out with checking the code where user input is taken and then placed into SQL statements from a SQL Injection point of view, I would also take a look if user input is echoed back without any treatment to see if there are issues with XSS. If these checks yield that the previous programming done carelessly, I would call IT department to an immediate meeting to discuss this matter. At that time, you either convince the IT department that the code needs to be re-written or a great patch work is due. But many times, writing code from the ground up yields way better results than trying to fix the problematic code. I think there are two kinds of programmers. Those with do what they are told and could not care less the rest and Those who stop their bosses and guide them in the proper track. On Mon, Sep 24, 2012 at 7:05 AM, AmirBehzad Eslami wrote: > Hi, > > i'm going to join a mid-size company with a few PHP-driven projects > written in procedural PHP, million years old. > > At the moment, they don't have a wiki or any documentation about their > projects. For me, the first challenge in probation period is to understand > how their code works. > * > Considering that there is no wiki or docs, How can I see the Big Picture?* > i'm sure this is a common problem for programmers everywhere. > > What approach do you use in a similar situation? > Is there a systematic approach for this? > Is there reverse-engineering technique to understand the design of code? > > Please share your experience and thoughts. > > -Thanks in advance, > Behzad -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP] Joining a team, where no wiki or docs are available
Thanks Samuel. Actually I'm not going to add features or fix bugs, they're trying a refactoring process, to improve the design of code. So, I really need to understand the current design at the outset. On Mon, Sep 24, 2012 at 5:41 PM, Samuel Lopes Grigolato < samuel.grigol...@gmail.com> wrote: > I would recommend reading this article: > http://www.infoq.com/articles/tips-to-developers-starting-on-large-apps > > It's targeted to Java developers, but the concepts are valid to any > language. > > Hope it helps. > > Cheers, > Samuel. >
