I've collected a number of my blog posts, which together may help you in the transition from Rails to JavaScript (or CoffeeScript) frontends. Many of the posts are about the mental transition you need to make along the way, while other posts are more technical.
I think it's best to read them in the order I put it here, as they present the road I took over the last 5 years.
1. Rails is not MVC
2. Frontend is a separate application
3. From backend to frontend, a mental transition
4. Is CoffeeScript better than Ruby?
5. JavaScript frontends are like desktop applications
6. Frontend first
7. Non-framework approach to JavaScript applications
8. Angular or Ember? Congratulations, you've already won
9. Single Page Applications - fight
10. Turn a Rails controller into a Single Page Application
11. How can Rails react to the rise of JavaScript frameworks?
12. Which JavaScript framework should I choose? (video)
If you enjoyed reading the blog posts, you may consider following me on Twitter.
Wednesday, February 11, 2015
Which JavaScript framework should I use? (video)
Over the last 4-5 years, I keep being asked this question - Which JavaScript framework should I use?
2.5 years ago, I had a talk at the RuPy conference, where I'm trying to answer this question. I realised, I've never posted the video to my blog. 2.5 years is like a century in the IT world. Everything has changed, right? I believe that my answer is still correct and all what I said is still true.
Enjoy the 30 minutes of my lecture :)
2.5 years ago, I had a talk at the RuPy conference, where I'm trying to answer this question. I realised, I've never posted the video to my blog. 2.5 years is like a century in the IT world. Everything has changed, right? I believe that my answer is still correct and all what I said is still true.
Enjoy the 30 minutes of my lecture :)
Tuesday, February 3, 2015
Splitting a Rails controller
Splitting a controller into separate files may be a good idea in certain cases.
Let me start with the cases, when it's NOT a good idea. In case of a simple CRUD controller, this may be an overkill. The same applies to simple, scaffold-like controllers.
Some controllers are more resource-oriented - those may benefit from keeping the actions together in one file. People often use filters for reusing certain rules of accessing the resources here.
Other controllers may be more action-oriented (as opposed to resource-oriented). It's typical for the your-main-model-controllers. In those controllers, you will see more than the standard actions. They will contain interesting logic for 'update', 'create', 'destroy'. Those actions may have different logic. Often, they don't share that much.
The action-oriented controllers may benefit from splitting them into several files. I call them SingleActionControllers.
Please, note that the action-oriented controllers can contain a more complicated set of rules in the controller filters. Often, they create a full algebra of filters, where you need to find your way through the :except clauses and dependencies between filters. Refactoring those places requires a really precise way of working.
Apart from the filters problem, extracting a SingleActionController is easy and consists of the following steps:
1. A new route declaration above the previous (first wins)
post 'products' => 'create_product#create'
resources :products, except: [:create]
2. Create an empty controller CreateProductController which inherits from the previous
3. Copy the action content to the new controller
4. Remove the action from the previous controller
5. Copy the filters/methods that are used by the action to the new controller
6. Make the new controller inherit from the ApplicationController
7. Change routes to add 'except: [:foo_action]'
You can also see a simple example of this refactoring here:
http://rails-refactoring.com/recipes/extract-single-action-controller-class/
TDDing a unit, not a class
Some time ago, I blogged about "Unit tests vs Class tests", where I described how it differs when you think of a unit more as a collection of classes instead of a single class.
Together they can make nice stories. You can start with a simple test like:
(if you don't like exceptions, you can turn it into returning true/false instead)
One by one, you could build the whole feature this way, while being test-driven all the time.
In a Rails app, you will then use this Authentication object from the Rails controllers. This is also a good way of improving Rails controllers.
This approach is sometimes called top-down. You start with the expectation from the higher module (Authentication) and this drives you to implement the lower-level classes like User and Session.
Another approach is called bottom-up, where you start with the User and Session classes from the beginning and don't worry with the wrapping module, yet.
The different approaches may result in different tests. With the top-down approach you end up with module tests, while with bottom-up most likely you end up with a test per class.
How can we TDD such a unit?
This reddit thread triggered me to explain it a bit more. The title of the thread was interesting: "How does one TDD a user and session model?"
Such question is a good example, how the class tests seem to be the default in the "unit testing" thinking. Instead of asking how to TDD the Authentication unit, we're asked how to TDD some single classes - which often depend on each other.
Here is my response:
One way to do it is to think one level higher. Don't focus on the User and Session classes, but focus on the whole feature/module that you're building. In this case, that's probably Authentication, right?
Think of Authentication as a class, which is a facade. It's very likely, that you will come up with User and Session classes, sooner or later. They will be more like implementation details.
You probably need to implement functions like:
One way to do it is to think one level higher. Don't focus on the User and Session classes, but focus on the whole feature/module that you're building. In this case, that's probably Authentication, right?
Think of Authentication as a class, which is a facade. It's very likely, that you will come up with User and Session classes, sooner or later. They will be more like implementation details.
You probably need to implement functions like:
- register
- logging in
- logging out
- change_password
- change_email
- change_login
- remember_me
- delete_user
Together they can make nice stories. You can start with a simple test like:
def test_wrong_credentials_dont_authenticate authentication = Authentication.new authentication.register_user("user", "password") assert_raises(WrongCredentials) { authentication.authenticate("user", "wrong password") } end
(if you don't like exceptions, you can turn it into returning true/false instead)
One by one, you could build the whole feature this way, while being test-driven all the time.
In a Rails app, you will then use this Authentication object from the Rails controllers. This is also a good way of improving Rails controllers.
This approach is sometimes called top-down. You start with the expectation from the higher module (Authentication) and this drives you to implement the lower-level classes like User and Session.
Another approach is called bottom-up, where you start with the User and Session classes from the beginning and don't worry with the wrapping module, yet.
The different approaches may result in different tests. With the top-down approach you end up with module tests, while with bottom-up most likely you end up with a test per class.
Sunday, January 4, 2015
Ruby and instance_variable_get - when it's useful?
When working on my book about refactoring Rails controllers, I've collected a number of "unusual" Rails solutions from real-world projects. They were either sent to me from the readers or I found them in some open-source Rails projects.
One of them was the idea of using instance_variable_get.
instance_variable_get in the Redmine project
I was working on one of the most important recipes from my book - "Explicitly render views with locals". It's important, as it opens the door to many other recipes - it makes them much simpler.
When I was practising this recipe, I tried to use it in many different projects. One of the open-source ones was Redmine. I applied this refactoring to one of the Redmine actions. I've searched through the view to find all @ivars and replaced them with an explicit object reference (passed to the view through the locals collection). This time it didn't work. The tests (Redmine has really high test coverage) failed.
The reason was a helper named error_messages_for(*objects). It's used in many Redmine views.
The implementation looks like this:
The idea behind this is to display error messages for multiple @ivars in a view. As you see, it uses the instance_variable_get calls to retrieve the @ivar from the current context. It's only used in cases, when a string is passed and not an @ivar directly.
This situation taught me 3 lessons.
1. I need to test my recipes in as many projects as possible to discover such edge cases.
2. A high test coverage gives a very comfortable situation to experiment with refactorings.
3. Ruby developers are only limited by imagination. The language doesn't impose any constraints. It's both good and bad.
I've extended the recipe chapter with a warning about the instance_variable_get usage:
The lifecycle of a Rails controller
After some time, I was working on another chapter called "Rails controller - the lifecycle". In that chapter I describe step by step what is happening when a request is made, starting from the routes, ending with rendering the view. Each step is associated with a snippet of the Rails code.
Everybody knows that if you have assign an @ivar in a controller, it's automatically available as an @ivar in the view object, even though they are different objects.
The trick here is that the Rails code uses instance_variable_get as well. It grabs all the instance variables and creates their equivalents in the view object using the instance_variable_set. Here is part of the chapter:
Easier debugging in rubygems code
In the rubygems code you will find this piece of code. It's a way of displaying the current state (@ivars) of the object. At first, it may look useful. I'm sure it served well for this purpose. However, the root problem here is not how to display the state. The root problem is that the state is so big here that it needs a little bit of meta programming to retrieve it easily. Solving the root problem (splitting it into more classes?) would probably reduce the need for such tricks.
When it's useful?
instance_variable_get is a way of bypassing the object encapsulation. There's a good reason that in Ruby we hide some state using @ivars. Such a hidden state may or may not be exposed in some way. I'd compare instance_variable tricks to using the "send" method.
My rule of thumb is that it's sometimes useful when you build a framework-like code. Code that will be used by other people via some kind of DSL. Rails is such an example. I'm not a big fan of copying the @ivars to the view, but I admit it plays some role in attracting new people to Rails.
However, it's a rare case, that instance_variable_get may be a good idea to use in your typical application.
The temptation to use it is often related to reducing the amount of code. That's a similar temptation to using the "send"-based tricks. I'm guilty of that in several cases. I learnt my lessons here. It might have been "clever" for me, but it was painful for others to understand. It's rarely worth the confusion.
I've seen enough legacy Rails projects to know, that sometimes the instance_variable_set trick is useful in tests. It's still "cheating", but it may be a good temporary step to get the project on the right path. Some modules/objects may be hard to test in isolation in a legacy context. Sometimes, we may need to take an object (like a controller) and set some of its state via instance_variable_set at the beginning of the test. It's similar to stubbing. This way we may be able to build a better test coverage. Test coverage on its own doesn't mean anything. However, good test coverage enables us to refactor the code, so that it no longer needs meta programming tricks.
When in doubt, don't use instance_variable_get.
One of them was the idea of using instance_variable_get.
instance_variable_get in the Redmine project
I was working on one of the most important recipes from my book - "Explicitly render views with locals". It's important, as it opens the door to many other recipes - it makes them much simpler.
When I was practising this recipe, I tried to use it in many different projects. One of the open-source ones was Redmine. I applied this refactoring to one of the Redmine actions. I've searched through the view to find all @ivars and replaced them with an explicit object reference (passed to the view through the locals collection). This time it didn't work. The tests (Redmine has really high test coverage) failed.
The reason was a helper named error_messages_for(*objects). It's used in many Redmine views.
The implementation looks like this:
The idea behind this is to display error messages for multiple @ivars in a view. As you see, it uses the instance_variable_get calls to retrieve the @ivar from the current context. It's only used in cases, when a string is passed and not an @ivar directly.
This situation taught me 3 lessons.
1. I need to test my recipes in as many projects as possible to discover such edge cases.
2. A high test coverage gives a very comfortable situation to experiment with refactorings.
3. Ruby developers are only limited by imagination. The language doesn't impose any constraints. It's both good and bad.
I've extended the recipe chapter with a warning about the instance_variable_get usage:
The lifecycle of a Rails controller
After some time, I was working on another chapter called "Rails controller - the lifecycle". In that chapter I describe step by step what is happening when a request is made, starting from the routes, ending with rendering the view. Each step is associated with a snippet of the Rails code.
Everybody knows that if you have assign an @ivar in a controller, it's automatically available as an @ivar in the view object, even though they are different objects.
The trick here is that the Rails code uses instance_variable_get as well. It grabs all the instance variables and creates their equivalents in the view object using the instance_variable_set. Here is part of the chapter:
Easier debugging in rubygems code
In the rubygems code you will find this piece of code. It's a way of displaying the current state (@ivars) of the object. At first, it may look useful. I'm sure it served well for this purpose. However, the root problem here is not how to display the state. The root problem is that the state is so big here that it needs a little bit of meta programming to retrieve it easily. Solving the root problem (splitting it into more classes?) would probably reduce the need for such tricks.
When it's useful?
instance_variable_get is a way of bypassing the object encapsulation. There's a good reason that in Ruby we hide some state using @ivars. Such a hidden state may or may not be exposed in some way. I'd compare instance_variable tricks to using the "send" method.
My rule of thumb is that it's sometimes useful when you build a framework-like code. Code that will be used by other people via some kind of DSL. Rails is such an example. I'm not a big fan of copying the @ivars to the view, but I admit it plays some role in attracting new people to Rails.
However, it's a rare case, that instance_variable_get may be a good idea to use in your typical application.
The temptation to use it is often related to reducing the amount of code. That's a similar temptation to using the "send"-based tricks. I'm guilty of that in several cases. I learnt my lessons here. It might have been "clever" for me, but it was painful for others to understand. It's rarely worth the confusion.
I've seen enough legacy Rails projects to know, that sometimes the instance_variable_set trick is useful in tests. It's still "cheating", but it may be a good temporary step to get the project on the right path. Some modules/objects may be hard to test in isolation in a legacy context. Sometimes, we may need to take an object (like a controller) and set some of its state via instance_variable_set at the beginning of the test. It's similar to stubbing. This way we may be able to build a better test coverage. Test coverage on its own doesn't mean anything. However, good test coverage enables us to refactor the code, so that it no longer needs meta programming tricks.
When in doubt, don't use instance_variable_get.
Sunday, December 28, 2014
How to write a Ruby-related book - the tools
I have recently published the 1.0 release of the "Rails Refactoring: Rails Controllers" book. It took me over 1 year since I started. Over the time, I've experimented with many tools which helped me along the way.
This post is a summary of some of the tools.
The short version
iaWriter for the initial writing
vim/sublime for editing
LeanPub for PDF/epub/mobi generation
Github for storing the source files (markdown)
DPD for selling
MailChimp for email list
Trello for task management
The longer version
After I knew what to write about (the process how I came up with the "idea" is another topic - let me know if you're interested in reading about it) - I've had a bunch of notes, scattered across many tools - Evernote, Hackpad, MindNode, code repositories.
Despite all the temptations, I didn't try to find the best tool for writing. I know myself and that would result in endless experiments without any delivery. Obviously, there was a temptation to write such tools on my own. I'm very happy I didn't go this way.
The minimal requirements was to have a tool that generates a PDF.
Kitabu
The first tool that seemed to be good enough was kitabu. It was a good tool - think Rails but for books, a whole framework.
They even give you the familiar "$ kitabu new mybook" tool.
Kitabu was a very programmer-friendly approach.
I eventually gave up on Kitabu. The problem was with the commercial PDF tool (PrinceXML) which is used by default. I was OK with paying for good software, but at that time, the license was about $2,000 which was a bit too high.
Scrivener
Then I switched to Scrivener. I loved this tool. I found it through some "real" writers forum. It's very popular among writers. It's a desktop app. It's great for notes collection, structuring, drafting. It's good at WYSIWYG. It has a built-in PDF generation. It supports export/import from markdown.
At some point, more people from my team started to help mi with the book. The Scrivener approach wasn't very team-friendly (or I wasn't able to use it). No easy way of two-way sync with markdown. Other people would have to be forced to use Scrivener as well. Also, it wasn't very version-control-friendly.
Leanpub
Meanwhile, Robert Pankowecki (with a little bit of my help) was working on the Developers Oriented Project Management book. He used Leanpub and this tool was very team-friendly. There was a repo, we could all contribute into. It generates PDF/mobi/epub (on their servers) via a Github hook.
The Github repo:
(as you see there were 300 commits so far and 13 people contributed to the book!)
I was sceptical at first, as they (at least at that time) didn't give emails from the book readers. I found it very limiting for marketing/sales activities. However, LeanPub lets you generate the PDF and take the files with you to sell somewhere else. That sounded perfect to us.
Over the last year, I've seen how Leanpub (the UI) keeps getting better. I may seriously consider switching to them as the selling tool as well at some point. They now also have an iOS app for reading your books.
So far, we're staying with Leanpub for our books (the third one is in progress).
My book is very code-heavy. LeanPub is great for it. They not only support syntax highlighting but they also let us present nicely the diff between two pieces of code.
One minor issue with Leanpub is that you need to wait for the PDF generation (30-60 seconds). I usually work locally, do frequent commits to the local repo. Every now and then I push to the github repo. This triggers a hook, which notifies Leanpub. After a while, I launch a simple bash script - download_and_preview.sh - which downloads the newest PDF and opens Preview on my Mac (if it's already open then it reloads the file). This is a good-enough flow.
iaWriter
Leanpub lets me write in MarkDown. For some time, I've used vim for that. After a while, I realized that there are two aspects of writing. When I write the initial version of a chapter I need a full focus to let the flow work. iaWriter is a perfect tool for distraction-free writing, with a beautiful full-screen mode. This is where I do most of my initial writing.
When the draft of the chapter is ready, I need to do more editing (it's like refactoring but for normal text). This is when I usually launch either vim or sublime. The vim shortcuts lets me do editing faster.
When I'm done and ready for a new release of the book, I run the 'release' script:
This created a capistrano-like directory and creates a new .zip file.
DPD
I use the DPD system for selling. Unfortunately, they don't have the API to automatically upload a new .zip file and manually change the product configuration. I hate this part, as it's very error-prone. I even attached the wrong file to the wrong product once.
As for payments, DPD only supports PayPal (at least for a Polish company, last time we checked), so this is what I went with. I'm not a big fan of PayPal, but it didn't seem to be a huge problem for all the buyers.
Whenever I have a new release, I can send an email from the DPD panel to all the customers, which automatically generates the appropriate download URL.
As you may expect, DPD gives you all the reporting, charts, data which you may need.
Slack
Over the time, we've created notifications around the whole process. Whenever a new commit is pushed into the repo, a new notification appears on a special Slack channel. Whenever a new sale is made, we have a SalesPanda bot which notifies us about it to the same channel.
Summary
As you see, the whole process is a combination of multiple tools. In some places, they are integrated automatically, while some places are still manually updated. The perfect setup would be to have a Continuous Delivery and we're very close to such thing here. When the delivery is a PDF, the problem is that you would need to email people on every Delivery. This doesn't sound perfect, though. With this book, I think I've had 4 releases so far and this worked well - starting from February 2014 until now.
Feel free to email me at andrzejkrzywda@gmail.com if you need any help with writing a book. It might be overwhelming at first.
The landing page (pure html/css) of the book mentioned in this post is here: http://rails-refactoring.com
This post is a summary of some of the tools.
The short version
iaWriter for the initial writing
vim/sublime for editing
LeanPub for PDF/epub/mobi generation
Github for storing the source files (markdown)
DPD for selling
MailChimp for email list
Trello for task management
The longer version
After I knew what to write about (the process how I came up with the "idea" is another topic - let me know if you're interested in reading about it) - I've had a bunch of notes, scattered across many tools - Evernote, Hackpad, MindNode, code repositories.
Despite all the temptations, I didn't try to find the best tool for writing. I know myself and that would result in endless experiments without any delivery. Obviously, there was a temptation to write such tools on my own. I'm very happy I didn't go this way.
The minimal requirements was to have a tool that generates a PDF.
Kitabu
The first tool that seemed to be good enough was kitabu. It was a good tool - think Rails but for books, a whole framework.
They even give you the familiar "$ kitabu new mybook" tool.
Kitabu was a very programmer-friendly approach.
I eventually gave up on Kitabu. The problem was with the commercial PDF tool (PrinceXML) which is used by default. I was OK with paying for good software, but at that time, the license was about $2,000 which was a bit too high.
Scrivener
Then I switched to Scrivener. I loved this tool. I found it through some "real" writers forum. It's very popular among writers. It's a desktop app. It's great for notes collection, structuring, drafting. It's good at WYSIWYG. It has a built-in PDF generation. It supports export/import from markdown.
At some point, more people from my team started to help mi with the book. The Scrivener approach wasn't very team-friendly (or I wasn't able to use it). No easy way of two-way sync with markdown. Other people would have to be forced to use Scrivener as well. Also, it wasn't very version-control-friendly.
Leanpub
Meanwhile, Robert Pankowecki (with a little bit of my help) was working on the Developers Oriented Project Management book. He used Leanpub and this tool was very team-friendly. There was a repo, we could all contribute into. It generates PDF/mobi/epub (on their servers) via a Github hook.
The Github repo:
(as you see there were 300 commits so far and 13 people contributed to the book!)
I was sceptical at first, as they (at least at that time) didn't give emails from the book readers. I found it very limiting for marketing/sales activities. However, LeanPub lets you generate the PDF and take the files with you to sell somewhere else. That sounded perfect to us.
Over the last year, I've seen how Leanpub (the UI) keeps getting better. I may seriously consider switching to them as the selling tool as well at some point. They now also have an iOS app for reading your books.
So far, we're staying with Leanpub for our books (the third one is in progress).
My book is very code-heavy. LeanPub is great for it. They not only support syntax highlighting but they also let us present nicely the diff between two pieces of code.
One minor issue with Leanpub is that you need to wait for the PDF generation (30-60 seconds). I usually work locally, do frequent commits to the local repo. Every now and then I push to the github repo. This triggers a hook, which notifies Leanpub. After a while, I launch a simple bash script - download_and_preview.sh - which downloads the newest PDF and opens Preview on my Mac (if it's already open then it reloads the file). This is a good-enough flow.
iaWriter
Leanpub lets me write in MarkDown. For some time, I've used vim for that. After a while, I realized that there are two aspects of writing. When I write the initial version of a chapter I need a full focus to let the flow work. iaWriter is a perfect tool for distraction-free writing, with a beautiful full-screen mode. This is where I do most of my initial writing.
When the draft of the chapter is ready, I need to do more editing (it's like refactoring but for normal text). This is when I usually launch either vim or sublime. The vim shortcuts lets me do editing faster.
When I'm done and ready for a new release of the book, I run the 'release' script:
This created a capistrano-like directory and creates a new .zip file.
DPD
I use the DPD system for selling. Unfortunately, they don't have the API to automatically upload a new .zip file and manually change the product configuration. I hate this part, as it's very error-prone. I even attached the wrong file to the wrong product once.
As for payments, DPD only supports PayPal (at least for a Polish company, last time we checked), so this is what I went with. I'm not a big fan of PayPal, but it didn't seem to be a huge problem for all the buyers.
Whenever I have a new release, I can send an email from the DPD panel to all the customers, which automatically generates the appropriate download URL.
As you may expect, DPD gives you all the reporting, charts, data which you may need.
Slack
Over the time, we've created notifications around the whole process. Whenever a new commit is pushed into the repo, a new notification appears on a special Slack channel. Whenever a new sale is made, we have a SalesPanda bot which notifies us about it to the same channel.
Summary
As you see, the whole process is a combination of multiple tools. In some places, they are integrated automatically, while some places are still manually updated. The perfect setup would be to have a Continuous Delivery and we're very close to such thing here. When the delivery is a PDF, the problem is that you would need to email people on every Delivery. This doesn't sound perfect, though. With this book, I think I've had 4 releases so far and this worked well - starting from February 2014 until now.
Feel free to email me at andrzejkrzywda@gmail.com if you need any help with writing a book. It might be overwhelming at first.
The landing page (pure html/css) of the book mentioned in this post is here: http://rails-refactoring.com
Monday, December 1, 2014
I'll refactor this later
Imagine this...
You're finishing your current ticket. The project manager keeps pinging you on IM, whether it's finished. This feature is important to a number of users. The business pressure is high. They want you to finish it ASAP.
"Could you deploy it before the lunch time?" - they beg.
You made some shortcuts in the code. It was just faster to put the code in the controller. You know how service objects are better, but this time it was just faster.
"I'll definitely be refactoring this later" - you think.
Just before the lunch, you push to master, run the deployment script. Everything seems to work. At the lunch, you're thinking how you're going to improve the code - extract the service object, add some more tests to cover the if branch that was added just at the last moment.
Back at the office. Everybody knows that you finished the previous ticket and the PM is happy. From the team perspective - you're now available for the next task.
"Could you help me debugging this problem?" - your colleague asks.
"We need the new reports in the admin panel" - the PM is back to you.
There's no way you can now fix the code shortcuts, you've made in the morning. You switched the context 3 times since then. There's just no time to do it. Other important things are waiting for you.
Did you just increase the technical debt? Is it your fault? You hate this kind of situations. You feel guilty.
Is there a way of avoiding such situations?
Can the code be debt-free?
In that story, you didn't manage to fix the code.
How it could have been done better?
Some people would say that you shouldn't deliver, before the code is great. The task is not finished, before the refactoring is finished.
"It's unprofessional" - they say.
There's some truth to that, but it's based on more assumptions.
"It's OK to have some technical debt, it's a pragmatic approach" - other people say. "Just document the problem somewhere" - they add.
Have you been in projects, where a special place for documenting the technical debt was created?
Some add it to the Pivotal/Redmine/wiki. Others try to keep a file in the repo - something like technical_debt.txt.
It can work, but it requires a huge discipline in the team. I used to be a big fan of this approach. After several approaches to it, now I think it's less realistic.
What are other options?
There's this "pragmatic" option to document the problem in the code comment. From what I see in the projects, I'm reviewing this may be the most popular option. I don't like it. I've looked at dozens of such comments, looked at the git repo history - the comments are almost always out of date. They're there and no one ever fixes the problem.
I really like another option. This practice alone isn't enough, but it's a good middle solution.
Document the hack in the git commit message.
Just write about the situation, why it was created like that, what were the time constraints. You may try to justify it a bit. You may explain how it can be fixed in the future.
Those messages are not part of the code, thus they don't make the code less readable. They are meta information, available to everyone, any time they want.
See a bad code? Just use your IDE to show the git logs for this place.
Bad code has other bad consequences. As developers, we like to point out the places, where code is wrong. Sometimes, a hack is implemented in 5 minutes (pragmatic), but then it takes 2 hours in the future for 2 people to discuss why it even got to the repository.
That's the real meaning of a debt. A 5-minute hack can turn into 2-hour discussion.
I've listed several approaches. I've tried them all. None of them is really good, right?
No hope then?
Well, there's another way of thinking. It's probably less spectacular and it requires better skills, but it can reduce most of the problems above.
First of all, there are hacks and hacks.
Some code should never be written in the first place. If you wrote a >100-lines method from scratch then it's a mess, not a code. Such code shouldn't go the repo. It doesn't matter if it's tested or not. There are some basic rules of coding that apply to our projects. It might be good for just spiking - writing some code to see if the concept can work. Afterwards it gets deleted.
Other cases are more on the technical debt side of things.
It's good to have such skills, that it doesn't make a time difference for you to write the code inside the action or in the service object. I just don't believe the time spent on typing those few characters/words more makes a difference. We're talking about seconds here, not even minutes.
More often, you're in situations, where you need to tweak some existing code to make the feature work. The original code wasn't yours - it doesn't even matter. What matters here is that this place requires a cleanup anyway. Let's say that you didn't have time to improve the existing code. There was no time for the Boy Scout rule. You've extended the existing action by some new 'if' statements. The whole path now works.
Now, this is the problematic situation. It's not your fault that the code was so bad at the beginning. You didn't improve it, though. You even made it worse. How much worse? It depends.
It's good to have a set of rules that all team agrees on.
Rails is so great, because it comes with conventions. As a team, you're not only choosing the web framework but also a convention framework. The problem is that at some point The Rails Way is not enough. This is the scary time when the team may not have enough guidelines. This is the time when it's not so clear anymore, where to put code and how to structure it.
That's why we coined the term The Next Way. It's a label to put some practices into. Service objects, form objects, adapters, repo objects. This is our way to solve the problem of missing conventions. It doesn't solve all of the problems, however it does help in limiting the length of the discussions.
The Next Way is just one possible set of conventions. We go with that but your team may choose anything else. What's important here is to have something that the team can agree on.
Thanks to The Next Way, we know what's the best format of a service object. Yes, there's lots of formats and discussing which one is best takes time.
So, The Next Way describes the goal. Your code is in point A and The Next Way code is Z. There's lots of steps in-between.
Being aware that improving code is a process helps a lot. Some would argue that being in point C is still bad. As long you as you all know that it's better than A - you can all agree that it's an improvement anyway.
Let's take an example here.
Imagine that your new feature requires displaying a new sentence in the view which shows the total value of the orders. The current view and action is very @ivar-heavy. There's no service object here, no repository objects as well. If you know The Next Way, then you know that removing @ivars is one of the steps we make to enable us for further steps.
In this interpretation, adding a new @ivar, like @total_order_value makes the code worse. It's not a big deal, but it's definitely not an improvement.
Now, what's good when you all have the commons set of techniques, like The Next Way is that everyone knows that it needs to be fixed. If you didn't have time to do it (like in the story we started with) in the first place - it doesn't really matter that much.
Why?
Because it's very easy to fix it. Once you know what is the goal, it's a matter of minutes to just turn the @ivar into an explicit rendering of a view following the "Explicitly Render Views with Locals" recipe.
Whoever next comes to this code and is more lucky with the business pressure can just fix it (with the help of the recipe if needed), commit, push, deploy. That's it. No lengthy discussions, no blaming, all clear.
I've seen many teams struggle when they entered the Beyond-The-Rails-Way phase. This phase is hard to avoid. When it happens, the team has problems with the consistency of the code. Sometimes the code looks like a collection of random blog posts. One technique here, another there. There are some good ideas, but there's no clear goal for all the code.
Once we've embraced The Next Way as a common set of techniques it was all easier. It is like The-Rails-Way-On-Steroids. It's more clear, where the code is. It's now clear when the code is in step C or closer to point Z.
What I'd like to encourage you to with this blogpost is to find your set of techniques in your team. This will help you and it will speed up your team work.
You can take what's in our book as a starting point and fork from there. The "Patterns" part of the book is all about The Next Way and its techniques. This is the description of the goal - the Z points. The "Recipes" chapter, on the other hand is all about the steps between the points.
Buy the book here
If you already bought the book, please consider starting the discussion in your team. Ask if it's clear what are the team conventions once The Rails Way is not enough.
Once you have the book, please don't just read it and put it away. The recipes need to be practiced regularly before they become a habit.
Start today - timebox 15 minutes, choose any action and try to apply the Recipe. I encourage you to start with the "Explicitly Render Views with Locals" one. It's a good start to get the feel of such changes.
There's a second episode of the Rails Refactoring Podcast - we're talking about the DNA of the Rails community and about The Rails Way. The whole episode is 35 minutes. We now also support RSS and iTunes, so subscribe to the podcast if you haven't done so yet :)
You're finishing your current ticket. The project manager keeps pinging you on IM, whether it's finished. This feature is important to a number of users. The business pressure is high. They want you to finish it ASAP.
"Could you deploy it before the lunch time?" - they beg.
You made some shortcuts in the code. It was just faster to put the code in the controller. You know how service objects are better, but this time it was just faster.
"I'll definitely be refactoring this later" - you think.
Just before the lunch, you push to master, run the deployment script. Everything seems to work. At the lunch, you're thinking how you're going to improve the code - extract the service object, add some more tests to cover the if branch that was added just at the last moment.
Back at the office. Everybody knows that you finished the previous ticket and the PM is happy. From the team perspective - you're now available for the next task.
"Could you help me debugging this problem?" - your colleague asks.
"We need the new reports in the admin panel" - the PM is back to you.
There's no way you can now fix the code shortcuts, you've made in the morning. You switched the context 3 times since then. There's just no time to do it. Other important things are waiting for you.
Did you just increase the technical debt? Is it your fault? You hate this kind of situations. You feel guilty.
Is there a way of avoiding such situations?
Can the code be debt-free?
In that story, you didn't manage to fix the code.
How it could have been done better?
Some people would say that you shouldn't deliver, before the code is great. The task is not finished, before the refactoring is finished.
"It's unprofessional" - they say.
There's some truth to that, but it's based on more assumptions.
"It's OK to have some technical debt, it's a pragmatic approach" - other people say. "Just document the problem somewhere" - they add.
Have you been in projects, where a special place for documenting the technical debt was created?
Some add it to the Pivotal/Redmine/wiki. Others try to keep a file in the repo - something like technical_debt.txt.
It can work, but it requires a huge discipline in the team. I used to be a big fan of this approach. After several approaches to it, now I think it's less realistic.
What are other options?
There's this "pragmatic" option to document the problem in the code comment. From what I see in the projects, I'm reviewing this may be the most popular option. I don't like it. I've looked at dozens of such comments, looked at the git repo history - the comments are almost always out of date. They're there and no one ever fixes the problem.
I really like another option. This practice alone isn't enough, but it's a good middle solution.
Document the hack in the git commit message.
Just write about the situation, why it was created like that, what were the time constraints. You may try to justify it a bit. You may explain how it can be fixed in the future.
Those messages are not part of the code, thus they don't make the code less readable. They are meta information, available to everyone, any time they want.
See a bad code? Just use your IDE to show the git logs for this place.
Bad code has other bad consequences. As developers, we like to point out the places, where code is wrong. Sometimes, a hack is implemented in 5 minutes (pragmatic), but then it takes 2 hours in the future for 2 people to discuss why it even got to the repository.
That's the real meaning of a debt. A 5-minute hack can turn into 2-hour discussion.
I've listed several approaches. I've tried them all. None of them is really good, right?
No hope then?
Well, there's another way of thinking. It's probably less spectacular and it requires better skills, but it can reduce most of the problems above.
First of all, there are hacks and hacks.
Some code should never be written in the first place. If you wrote a >100-lines method from scratch then it's a mess, not a code. Such code shouldn't go the repo. It doesn't matter if it's tested or not. There are some basic rules of coding that apply to our projects. It might be good for just spiking - writing some code to see if the concept can work. Afterwards it gets deleted.
Other cases are more on the technical debt side of things.
It's good to have such skills, that it doesn't make a time difference for you to write the code inside the action or in the service object. I just don't believe the time spent on typing those few characters/words more makes a difference. We're talking about seconds here, not even minutes.
More often, you're in situations, where you need to tweak some existing code to make the feature work. The original code wasn't yours - it doesn't even matter. What matters here is that this place requires a cleanup anyway. Let's say that you didn't have time to improve the existing code. There was no time for the Boy Scout rule. You've extended the existing action by some new 'if' statements. The whole path now works.
Now, this is the problematic situation. It's not your fault that the code was so bad at the beginning. You didn't improve it, though. You even made it worse. How much worse? It depends.
It's good to have a set of rules that all team agrees on.
Rails is so great, because it comes with conventions. As a team, you're not only choosing the web framework but also a convention framework. The problem is that at some point The Rails Way is not enough. This is the scary time when the team may not have enough guidelines. This is the time when it's not so clear anymore, where to put code and how to structure it.
That's why we coined the term The Next Way. It's a label to put some practices into. Service objects, form objects, adapters, repo objects. This is our way to solve the problem of missing conventions. It doesn't solve all of the problems, however it does help in limiting the length of the discussions.
The Next Way is just one possible set of conventions. We go with that but your team may choose anything else. What's important here is to have something that the team can agree on.
Thanks to The Next Way, we know what's the best format of a service object. Yes, there's lots of formats and discussing which one is best takes time.
So, The Next Way describes the goal. Your code is in point A and The Next Way code is Z. There's lots of steps in-between.
Being aware that improving code is a process helps a lot. Some would argue that being in point C is still bad. As long you as you all know that it's better than A - you can all agree that it's an improvement anyway.
Let's take an example here.
Imagine that your new feature requires displaying a new sentence in the view which shows the total value of the orders. The current view and action is very @ivar-heavy. There's no service object here, no repository objects as well. If you know The Next Way, then you know that removing @ivars is one of the steps we make to enable us for further steps.
In this interpretation, adding a new @ivar, like @total_order_value makes the code worse. It's not a big deal, but it's definitely not an improvement.
Now, what's good when you all have the commons set of techniques, like The Next Way is that everyone knows that it needs to be fixed. If you didn't have time to do it (like in the story we started with) in the first place - it doesn't really matter that much.
Why?
Because it's very easy to fix it. Once you know what is the goal, it's a matter of minutes to just turn the @ivar into an explicit rendering of a view following the "Explicitly Render Views with Locals" recipe.
Whoever next comes to this code and is more lucky with the business pressure can just fix it (with the help of the recipe if needed), commit, push, deploy. That's it. No lengthy discussions, no blaming, all clear.
I've seen many teams struggle when they entered the Beyond-The-Rails-Way phase. This phase is hard to avoid. When it happens, the team has problems with the consistency of the code. Sometimes the code looks like a collection of random blog posts. One technique here, another there. There are some good ideas, but there's no clear goal for all the code.
Once we've embraced The Next Way as a common set of techniques it was all easier. It is like The-Rails-Way-On-Steroids. It's more clear, where the code is. It's now clear when the code is in step C or closer to point Z.
What I'd like to encourage you to with this blogpost is to find your set of techniques in your team. This will help you and it will speed up your team work.
You can take what's in our book as a starting point and fork from there. The "Patterns" part of the book is all about The Next Way and its techniques. This is the description of the goal - the Z points. The "Recipes" chapter, on the other hand is all about the steps between the points.
Buy the book here
If you already bought the book, please consider starting the discussion in your team. Ask if it's clear what are the team conventions once The Rails Way is not enough.
Once you have the book, please don't just read it and put it away. The recipes need to be practiced regularly before they become a habit.
Start today - timebox 15 minutes, choose any action and try to apply the Recipe. I encourage you to start with the "Explicitly Render Views with Locals" one. It's a good start to get the feel of such changes.
There's a second episode of the Rails Refactoring Podcast - we're talking about the DNA of the Rails community and about The Rails Way. The whole episode is 35 minutes. We now also support RSS and iTunes, so subscribe to the podcast if you haven't done so yet :)
Subscribe to:
Posts (Atom)