Re: Framework & Code Re-Factoring: Maintaining Quality

[Taher Alkhateeb <sl...@gmail.com>]

Hello everyone,

We already discussed in detail the best practices and guidelines for
refactoring (review the rest of this thread).

I am writing this email instead to focus on an important point that I'm
noticing in the code base and the refactoring exercise. Forget all the
details for a moment and focus on this one guiding principle: _Code should
be clear_

What this means is that the code you wrote is done with care and love.
Method names clearly explain what they're supposed to do. Your code starts
at high level and goes down to details. I can read it like a story, it
makes sense, it's easy on the eyes, You can almost say It's boring.

One of the best ways to confuse other developers is to have hidden state.
You declare a global variable and manipulate it in a 100 different places
in your code and it's not even passed to those places, you just yank it!

Another place which is badly implemented in many places in ofbiz is methods
(functions). All the below guidelines can improve these methods:
- The names should reflect intention. It's much better to name something
like retrievePersonDetails(...) than retrieveStringList(...)
- They should be small enough to fit in your screen, preferably even
shorter.
- They should do _only one thing_. Don't fetch data, validate it, and then
send it to the screen all in one place. Each one of those things is a
function, and then you can combine them in one master function or object.
- They should be at the same level of abstraction (don't mix high level
stuff with details)

Food for thought for those interested.

Taher Alkahteeb

On Fri, Apr 8, 2016 at 3:58 PM, Ron Wheeler <rw...@artifact-software.com>
wrote:

> Just a reminder to everyone that there is an ongoing Skype conversation
> around the framework refactoring sub-project.
> If you are not part of the conversation, please ask to join.
>
> It is not very active so you will not get a lot of notes to read
> However, it provides a place where you can quickly get input from the rest
> of the team working on the sub-project.
>
> It is a good place to look for feedback or advice before you start to work
> on a task or have to make a design choice that may have affects on other
> parts of the project.
>
> There is also a much larger group on Skype that is more active that
> involves many of those working on OFBiz in general.
>
> You can join these groups even if you are not currently actively
> contributing to the project.
>
> That being said, the Skype conversations are not designed to replace the
> wiki of the ML so don't forget to confirm decisions or summarize important
> discussions in the appropriate official record.
>
> Ron
> PS:
> Taher's recommended readings are worth a quick read.
> Well written.
> Lots of good ideas and important reminders about coding practices.
>
>
> -
> On 08/04/2016 8:18 AM, Taher Alkhateeb wrote:
>
>> Hi Sharan and all,
>>
>> To all contributors to the project, I highly recommend reading:
>>
>> - Refactoring: Martin Fowler
>> - Clean Code: Robert Martin (AKA uncle Bob)
>> - SOLID principles of OOP
>> - Test Driven Development (TDD)
>>
>> I also encourage fellow committers to think of design changes and areas
>> they dislike in the framework to add to the list in the wiki page. I'm
>> sure
>> with the combined expertise of everyone we can speed up this project a
>> lot.
>>
>> Regards,
>> Taher Alkhateeb
>>
>> On Friday, 8 April 2016, Pranay Pandey <pr...@hotwaxsystems.com>
>> wrote:
>>
>> +1 will be extra careful going forward.
>>>
>>> Best regards,
>>>
>>> Pranay Pandey
>>> HotWax Systems
>>> http://www.hotwaxsystems.com/
>>>
>>> On Fri, Apr 8, 2016 at 12:36 PM, Sharan-F <sharan.foga@gmail.com
>>> <javascript:;>> wrote:
>>>
>>> Hi Everyone
>>>>
>>>> It's great to see the progress happening on the framework and code
>>>> re-factoring.  Tasks from our to do list are being picked up and worked
>>>>
>>> on,
>>>
>>>> so thank you to everyone involved in this.
>>>>
>>>> As this is a code clean-up, I'd really like to emphasize that we need to
>>>>
>>> be
>>>
>>>> extra careful because we are changing the way we currently code. This
>>>>
>>> means
>>>
>>>> that there is some extra responsibility for the committers in the review
>>>> process to ensure that the quality of the code going in is an
>>>> improvement
>>>> to
>>>> the existing code (I.e we dont want to commit anything that keeps our
>>>>
>>> code
>>>
>>>> untidy or makes it even worse)
>>>>
>>>> If we can include stronger quality checks while the re-factoring is
>>>> going
>>>> on, we can be sure that we are definitely making and delivering code
>>>> improvements.
>>>>
>>>> What do people think?
>>>>
>>>> Thanks
>>>> Sharan
>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> View this message in context:
>>>>
>>>>
>>> http://ofbiz.135035.n4.nabble.com/Framework-Code-Re-Factoring-Maintaining-Quality-tp4679123.html
>>>
>>>> Sent from the OFBiz - Dev mailing list archive at Nabble.com.
>>>>
>>>>
>
> --
> Ron Wheeler
> President
> Artifact Software Inc
> email: rwheeler@artifact-software.com
> skype: ronaldmwheeler
> phone: 866-970-2435, ext 102
>
>

Re: Framework & Code Re-Factoring: Maintaining Quality

[Taher Alkhateeb <sl...@gmail.com>]

hi Sharan

I think code clarity was not emphasized in the guidelines. but I would
prefer to put it at the top of the page in bold headers.

Really I think we should stop thinking of our selves as ninja coders and
more like poets and writers. Contrary to common belief coding is a very
social activity and when you write beautiful clear code you are showing
appreciation and respect to your fellow programmers.

I don't know how to put that last part in the guidelines :) but this is
definitely from the heart.

Taher Alkhateeb

On Thursday, 26 May 2016, Sharan-F <sh...@gmail.com> wrote:

> Hi Taher
>
> Thanks for sharing and I know it's coming from going through some tough
> code
> interpreting experiences. Have these ideas been captured in our best coding
> practises?
>
> Thanks
> Sharan
>
>
>
> --
> View this message in context:
> http://ofbiz.135035.n4.nabble.com/Framework-Code-Re-Factoring-Maintaining-Quality-tp4679123p4681679.html
> Sent from the OFBiz - Dev mailing list archive at Nabble.com.
>

Re: Framework & Code Re-Factoring: Maintaining Quality

[Sharan-F <sh...@gmail.com>]

Hi Taher

Thanks for sharing and I know it's coming from going through some tough code
interpreting experiences. Have these ideas been captured in our best coding
practises? 

Thanks
Sharan



--
View this message in context: http://ofbiz.135035.n4.nabble.com/Framework-Code-Re-Factoring-Maintaining-Quality-tp4679123p4681679.html
Sent from the OFBiz - Dev mailing list archive at Nabble.com.

Re: Framework & Code Re-Factoring: Maintaining Quality

[Ron Wheeler <rw...@artifact-software.com>]

+1
Words to live by.
Words to review commits by.
The fact that code "works" is only one thing to consider before 
accepting the obligation of maintaining it forever.

Ron

On 26/05/2016 2:38 AM, Taher Alkhateeb wrote:
> Hello everyone,
>
> We already discussed in detail the best practices and guidelines for
> refactoring (review the rest of this thread).
>
> I am writing this email instead to focus on an important point that I'm
> noticing in the code base and the refactoring exercise. Forget all the
> details for a moment and focus on this one guiding principle: _Code should
> be clear_
>
> What this means is that the code you wrote is done with care and love.
> Method names clearly explain what they're supposed to do. Your code starts
> at high level and goes down to details. I can read it like a story, it
> makes sense, it's easy on the eyes, You can almost say It's boring.
>
> One of the best ways to confuse other developers is to have hidden state.
> You declare a global variable and manipulate it in a 100 different places
> in your code and it's not even passed to those places, you just yank it!
>
> Another place which is badly implemented in many places in ofbiz is methods
> (functions). All the below guidelines can improve these methods:
> - The names should reflect intention. It's much better to name something
> like retrievePersonDetails(...) than retrieveStringList(...)
> - They should be small enough to fit in your screen, preferably even
> shorter.
> - They should do _only one thing_. Don't fetch data, validate it, and then
> send it to the screen all in one place. Each one of those things is a
> function, and then you can combine them in one master function or object.
> - They should be at the same level of abstraction (don't mix high level
> stuff with details)
>
> Food for thought for those interested.
>
> Taher Alkahteeb
>
> On Fri, Apr 8, 2016 at 3:58 PM, Ron Wheeler <rw...@artifact-software.com>
> wrote:
>
>> Just a reminder to everyone that there is an ongoing Skype conversation
>> around the framework refactoring sub-project.
>> If you are not part of the conversation, please ask to join.
>>
>> It is not very active so you will not get a lot of notes to read
>> However, it provides a place where you can quickly get input from the rest
>> of the team working on the sub-project.
>>
>> It is a good place to look for feedback or advice before you start to work
>> on a task or have to make a design choice that may have affects on other
>> parts of the project.
>>
>> There is also a much larger group on Skype that is more active that
>> involves many of those working on OFBiz in general.
>>
>> You can join these groups even if you are not currently actively
>> contributing to the project.
>>
>> That being said, the Skype conversations are not designed to replace the
>> wiki of the ML so don't forget to confirm decisions or summarize important
>> discussions in the appropriate official record.
>>
>> Ron
>> PS:
>> Taher's recommended readings are worth a quick read.
>> Well written.
>> Lots of good ideas and important reminders about coding practices.
>>
>>
>> -
>> On 08/04/2016 8:18 AM, Taher Alkhateeb wrote:
>>
>>> Hi Sharan and all,
>>>
>>> To all contributors to the project, I highly recommend reading:
>>>
>>> - Refactoring: Martin Fowler
>>> - Clean Code: Robert Martin (AKA uncle Bob)
>>> - SOLID principles of OOP
>>> - Test Driven Development (TDD)
>>>
>>> I also encourage fellow committers to think of design changes and areas
>>> they dislike in the framework to add to the list in the wiki page. I'm
>>> sure
>>> with the combined expertise of everyone we can speed up this project a
>>> lot.
>>>
>>> Regards,
>>> Taher Alkhateeb
>>>
>>> On Friday, 8 April 2016, Pranay Pandey <pr...@hotwaxsystems.com>
>>> wrote:
>>>
>>> +1 will be extra careful going forward.
>>>> Best regards,
>>>>
>>>> Pranay Pandey
>>>> HotWax Systems
>>>> http://www.hotwaxsystems.com/
>>>>
>>>> On Fri, Apr 8, 2016 at 12:36 PM, Sharan-F <sharan.foga@gmail.com
>>>> <javascript:;>> wrote:
>>>>
>>>> Hi Everyone
>>>>> It's great to see the progress happening on the framework and code
>>>>> re-factoring.  Tasks from our to do list are being picked up and worked
>>>>>
>>>> on,
>>>>
>>>>> so thank you to everyone involved in this.
>>>>>
>>>>> As this is a code clean-up, I'd really like to emphasize that we need to
>>>>>
>>>> be
>>>>
>>>>> extra careful because we are changing the way we currently code. This
>>>>>
>>>> means
>>>>
>>>>> that there is some extra responsibility for the committers in the review
>>>>> process to ensure that the quality of the code going in is an
>>>>> improvement
>>>>> to
>>>>> the existing code (I.e we dont want to commit anything that keeps our
>>>>>
>>>> code
>>>>
>>>>> untidy or makes it even worse)
>>>>>
>>>>> If we can include stronger quality checks while the re-factoring is
>>>>> going
>>>>> on, we can be sure that we are definitely making and delivering code
>>>>> improvements.
>>>>>
>>>>> What do people think?
>>>>>
>>>>> Thanks
>>>>> Sharan
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> View this message in context:
>>>>>
>>>>>
>>>> http://ofbiz.135035.n4.nabble.com/Framework-Code-Re-Factoring-Maintaining-Quality-tp4679123.html
>>>>
>>>>> Sent from the OFBiz - Dev mailing list archive at Nabble.com.
>>>>>
>>>>>
>> --
>> Ron Wheeler
>> President
>> Artifact Software Inc
>> email: rwheeler@artifact-software.com
>> skype: ronaldmwheeler
>> phone: 866-970-2435, ext 102
>>
>>


-- 
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102