blog:enterprise_clojure_is_not_a_bad_phrase
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
blog:enterprise_clojure_is_not_a_bad_phrase [2017/05/24 22:44] djo ['Enterprise Clojure' and Specs] |
blog:enterprise_clojure_is_not_a_bad_phrase [2017/05/25 16:16] djo removed |
||
|---|---|---|---|
| Line 63: | Line 63: | ||
| ===== As complexity increases, the data expected in a function's parameters can quickly become non-obvious ===== | ===== As complexity increases, the data expected in a function's parameters can quickly become non-obvious ===== | ||
| - | Even though I had written a docstring for the function, notice that because this function is a reducer, and is not API, I had not rigorously described each parameter's possible values and usage within the function. | + | Even though I had written a docstring for the ''%%merge-strings%%'' function, notice that because this function is a reducer, is used as internal implementation detail, and is not API, I had not rigorously described each parameter's possible values and usage within the function. |
| This week, I decided to use the upcoming [[https://clojure.org/guides/spec|Specs]] library from Clojure 1.9 to document each parameter's possible values and see if this helped with the readability and maintainability of this particular example. | This week, I decided to use the upcoming [[https://clojure.org/guides/spec|Specs]] library from Clojure 1.9 to document each parameter's possible values and see if this helped with the readability and maintainability of this particular example. | ||
| Line 155: | Line 155: | ||
| * I felt the experiment was successful. I believe the code I wound up with explains the original author's intentions better than the original code. | * I felt the experiment was successful. I believe the code I wound up with explains the original author's intentions better than the original code. | ||
| * Only time will validate the ''%%=>%%'' macro, and I'm sure it will evolve over time. But I sincerely hope something like it makes it into Specs in the end. | * Only time will validate the ''%%=>%%'' macro, and I'm sure it will evolve over time. But I sincerely hope something like it makes it into Specs in the end. | ||
| - | * More generally, I feel that this code illustrates how even quite straightforward functions can become opaque very quickly, and how providing explicit specifications describing what data a function accepts and provides can significantly enhance communication. | + | * More generally, I feel that this code illustrates how even quite straightforward functions can become opaque very quickly, and how providing explicit specifications describing what data a function accepts/provides can significantly enhance communication. |
| ==== ...and a word from our sponsors ==== | ==== ...and a word from our sponsors ==== | ||
| In closing, I'm available for new gigs right now. If this kind of thinking and expertise is welcome on your team or on your project (whatever the language), feel free to email me using the address on the "Contacts" page off my home page. | In closing, I'm available for new gigs right now. If this kind of thinking and expertise is welcome on your team or on your project (whatever the language), feel free to email me using the address on the "Contacts" page off my home page. | ||
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution 4.0 International
