For many of us this project was, and will be our first real glimpse at a project where not only is it required that we have a set way to structure, plan, organize and collaborate with one another, but it is essential to produce an end product that is not only functional, but easily maintainable and extendable for future iterations. Of course this is easier said than done. We have seen in class what is considered the "correct" way to go about this, but until you actually go and try it for yourself you will never know what really works and what doesn't. Now that we are done with iteration 1 I would like to share my thoughts on what worked and what didn't.
Looking back at iteration 1 I think one of the biggest mistakes we made was wanting to have something to show for our work right away rather than to sit down and plan everything out first. One of the biggest things that failed to plan for right away was the formatting of our code. Now part of this wasn't our fault because we started working on iteration 1 before we had the lecture about coding styles, and how not only would we be graded on the consistency of our formatting but why it is important to be consistent. And although my partner and I coded in a very similar style we both definitely had some things we did very different.
One example is where we placed our else statements. I placed it on the same line as the closing curly brace while my partner placed it on the line below. This may seem like something that doesn't really matter. We both knew what each other's code said and the slight difference in style was easy to get used to, but this slight syntactical difference lead to the dilemma of what to do when editing code in and around this. If the function I am currently coding in was originally created by my partner should I use his style to keep it consistent or should I use mine? Or should we use the style of the original author of the file? If you do this in enough places and with enough slight formatting differences that you end up with a codebase that doesn't look neat and organized and therefore is harder to read and ultimately modify and manage.
We spent a lot of time going through our code and fixing these formatting errors that could have been avoided if we had just sat down before hand and decided on exactly what our formatting standards would be for absolutely everything. Even though planning ahead is very helpful it might not catch everything. You see there was one thing that we did decide on before we got started, and that was that our indentation would be 4 spaces for each level. So I went and set my tab to be displayed as 4 spaces while my partner set his editor to not only display tabs as being 4 spaces, but also to insert 4 spaces rather than the '\t' character when he pressed space. This caused a ton of formatting errors because although the code that we each wrote looked good on our system when we looked at each other's code the indentations were way off and it actually took us a while to figure out why this was happening since we both had our tabs equal to 4 spaces. In spite of the short comings in our planning of formatting we did plan out the structure of our program in detail before we started which I think was the one thing we did that was crucial to our success in iteration 1.
Before my partner and I wrote even a line of code we say down and decided in detail what exactly the structure of our program would look like. This went from as high level as to discussing exactly what the program should be able to accomplish at the end of the iteration, to as detailed as defining each and every function in each class, their names, arguments and their output. The reason this was so important was because it allowed each of us to write our code and tests in a way that would be fully compatible with all of our partners code and we wouldn't have to worry about tweaking our code to fit with each other's. In addition, getting together and discussing how the overall structure should work lead both of us to give insight into the most efficient and easy to maintain code that we could possibly write that we wouldn't have come up with on our own. This is definitely something that wasn't explicitly talked about in class but I feel is something that we will keep doing in future iterations to make the work as easy as possible.
Another aspect of our planning that I believe will really help us out in future iterations is that we were constantly thinking about how to organize our data so that it would be the most flexible in terms of not only integrating with future iterations but also changes in how the data was used and accessed. For example, in iteration 1 the main type of data that had to be maintained and matched was the token names and their corresponding regexes. At first we thought about just having another array that stored each regex string in the exact same order as the token enum. This seems like a logical way to go about this, but because these two data structures would be defined apart any change in ordering or content would need to be reflected in the other and is very prone to errors as well as makes the code very hard to understand. We finally decided that we should instead use a vector where each element was a pair of the regex string and its corresponding terminal type. Although this took a little bit longer to set up, it is much more flexible and easy to read and understand and I believe will make integrating new iterations easier.
Furthermore, something that we did that really seemed to be helpful was to actually write tests while we wrote our code. This seems really obvious but I probably wouldn't have written tests for this if it wasn't required because the coding itself wasn't that difficult and most functions really weren't that complicated I think the benefit really became evident to me when we were adding new features or changing old ones. Since we already had the tests, we knew right away when tweaking some code completely messed up something else and we could diagnose and fix the problems much quicker because we knew exactly what change caused the problem.
The final part of the project that I was surprised to find helpful was to actually work with a partner. Of course I could have finished iteration 1 on my own, but I feel that working with a partner made it such a much greater learning experience because it forced me to plan ahead rather than just start coding. Also, it lead me to see solutions to problems that maybe wouldn't have been the way I would have solved it, but it ended up working, and even worked better than my solutions. I think that this is important because I get to comfortable doing things one way that works, but then I don't get to see different solutions that may be better, or may help me to solve another problem that I didn't know how to solve elegantly before. Finally, I think that working with a partner on this project is helpful because it gives me practice with stating my ideas in a way that other people can understand. This is a crucial skill when it comes to getting a real job because odds are you will work with others and you will need to discuss with them on a daily basis.
As you can see, during iteration 1 my partner and I did a lot of things that seemed to really work and helped us to finish on time as well as to produce a codebase that is easy to read and maintainable. We also did a few things that we should have done differently, but all we can do is learn from our mistakes and try to avoid them in the future. I hope that you find my experience helps you solve some of the problems you have faced, or maybe even to give you a whole new idea for how to make iteration 2 as easy as possible.