Consistent Coding Style #60
Comments
|
Hi @frink , Thank you for opening this issue. I think no small detail is too small for consideration.
I was unaware of that and would love to get some more information before making a decision. I was following the Ruby naming conventions, probably since the first iteration for the library was designed to be implemented as a Ruby extension. I know that PHP uses the whole word ( And although I am aware that Again, I really don't mind fixing a bad naming choice for the 0.8.x release cycle. I'm already planning some breaking changes that should homogenize the API for the core type... I just prefer to make a good choice. |
|
Interesting. I've never seen the Ruby way before... and I've been programing for 20+ years. Learn something new every day. But you are right. Further research does show a competing standard. Here are cliffnotes from my deeper dive... I did a quick search from comparing top result via Google and looking if they are relevant results. For each language I search, "arr" array $lang and "ary" array $lang. I wasn't so much concerned with search volume as I was with search accuracy as to what Google recognizes. (Ary is proper name and gives false positives, also blockarray has something called ARY, etc...) Bash, C#, C++, Go, PHP, Python and JavaScript prefer arr. Ruby definitely prefers ary. Lua, Java, Erlang and Perl seemed to slightly prefer arr but this may be my own prejudice - really they are too close to call. But I guess the real question here is which way C prefers... I grepped (via github) a random smattering of common C project .c files only... glibc - arr: 29 files - ary: 0 files Most cases where ary was mentioned was the phrase N-ary... After all this it occurred to me to search all of Github code directly. I searched for "arr" "ary" "arr array" and "ary array". Here are the results: Without searching for array: Searching for array too: I conclude from this that arr is definitely the preferred abbreviation in C. Also it is the clear leader in other web languages such as PHP, JavaScript, Python and Go. Bottom line: Should we rename things? |
|
@frink , Thank you very much for the detailed response. I think your information provides a very important perspective and I am almost convinced to rename the array API. I'm not writing this library only for myself and I agree that the naming should be intuitive for the majority of programmers rather than the minority - even if, personally, I feel In other words, a name change is probably in order. The only thing I am uncomfortable with is the fact that As far as API naming goes, it seems that JavaScript, PHP, node.js, Erlang, Objective-C ( C++ and Rust uses Perhaps facil.io should adopt a full name approach, as in I would appreciate any input from anyone reading this discussion. Kindly, |
|
I personally love the ARY syntax better. I use that over ARR all the time. It just feels better. however fiobj_array == ary in my book they both feel the same to me as apposed to arr. Just my humble opinion you asked and i was following the conversation :).
… On May 8, 2019, at 12:00 PM, Bo ***@***.***> wrote:
@frink <https://github.com/frink> ,
Thank you very much for the detailed response. I think your information provides a very important perspective and I am almost convinced to rename the array API.
I'm not writing this library only for myself and I agree that the naming should be intuitive for the majority of programmers rather than the minority - even if, personally, I feel ary is more "correct" (similar to apt for apartment).
In other words, a name change is probably in order.
The only thing I am uncomfortable with is the fact that arr abbreviations are usually used by programmers for variable naming, it isn't used as much for API naming.
As far as API naming goes, it seems that JavaScript, PHP, node.js, Erlang, Objective-C (NSArray) and Swift prefer to keep the whole of the name (array / Array) rather than abbreviate.
C++ and Rust uses vector (or Vec), which I simply refuse to adopt - only people who never studied physics could imagine vector as a collection of elements.
Perhaps facil.io should adopt a full name approach, as in fiobj_array instead of fiobj_ary or fiobj_arr... I will need to sleep on it for a bit.
I would appreciate any input from anyone reading this discussion.
Kindly,
Bo.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub <#60 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH5NB6ORIVBIYWISVC6O5OTPUL2IDANCNFSM4HK374KQ>.
|
|
If array is not abbreviated then it will not disrupt either group who are used to typing ary or arr.
As I said before, the only reason I mention this is because someone who is using Facil regularly is likely to get annoyed if they are used to using arr instead of ary. I found the annoyance large enough that year of Facil would get me frustrated enough to fork it just so I didn't have to go outside what is comfortable to me. But I realize I'm not the whole world and I want to be fair to all. @pr0con provides the best solution that avoids personal taste in view of pedantic completeness. This is probably the right choice for a framework which caters to all and cannot afford to get into a debate of personal taste... |
|
I've got some freetime over the weekend if you want me to build this out. Just want to know which branch to do the PR for... |
|
Actually, the name change is mostly done I moved all the dynamic types into a macro based header library in thecore-type-updates-(pre0.8.x) branch. I kept the ARY shortcut in the macros defining the dynamic array type, but I renamed the After I finish updating the new core FIOBJ types and API, I need to finish the documentation and port the existing features to the new API. You're welcome to pitch in 👍🏻 ... However, I got sidetracked trying to re-write the The standard |
|
Give me some clear direction and I'll jump in! :-D |
|
Wow! That's some pretty interesting use of macros. You've turned the whole thing into an implementation of MACRO+MACRO... Very interesting. Avoid anymore debate about naming. Please everybody... |
That's a great idea! I've started a Project with an initial to-do list. It's still a bit on the general side, but I guess details will be added as we go.
Thanks... I think. I know it can be harder to browse through the source-code this way, but it's make it so much more flexible. This approach is more modular and it makes it super simple to create different types with different properties using a few MACROs and an include statement.
I have much to learn about directing a workflow. I'm used to working alone or taking instructions (and I'm not even very good at taking instructions)... So feel free to pick something you would enjoy working on rather than something that feel like a grind. If I could pick one big focus: I would love it if you reviewed the API and complained about any inconsistencies or poor naming choices. I don't want to create the API again if I can avoid it, so it would be great to have another pair of eyes making sure the API is intuitive and easy to use. |
|
Okay I'll dig into the API. Then probably look at the inclusion of BearSSL next so we can make the whole thing embeddable as a static library. That should give us most of the exciting pieces of what's been scoped out. |
|
Wanted to report my progress in reviewing naming and ensuring we never need to argue about names again. It's turned into quite a bit more work than we originally envisioned. The big aha is understanding the reason WHY to use array as opposed to arr or ary and how that directs all other usage. This lead to changing the macros to be abbreviated and more descriptive. While I expect that we will probably go back and use macro naming conventions everywhere else, I found it easier to expand everything first for the sake of readability. It's really night and day difference. Ideally, I expect all usage of abbreviations to be expanded to full words. This will allow the most standard readability of the code. Then we can use macro naming to abbreviate according to the wishes of those who include this in their own codebase. Here is my current progress:
There is still a bit of work to do before I'm ready to call this viable. I'm still in the conversion phase of the source code. I've NOT tried to compile yet. I've decided to wait on that until I'm done playing origami with names. Everything is in a separate branch based off of the core-types-update(pre0.8.x) branch you mentioned. Here are some points of contention:
Digging into this it's been interesting thinking through all different viewpoints. I wasn't intending a huge renaming of everything when I got started. But, the argument for using array over arr or ary leads us down the path of fully semantic naming conventions. I decided to try this and I'm surprised how much more readable the code becomes spelling things out. That's why I've continued down this path. I truly believe this will give our users the most readable code. WIll probably take me another week before I'm ready to issue a pull request. But we're getting close... |
|
Oh one more thing I'm trying to understand is when to use multiple underscores in functions... e.g. xxx____yyy() Why are we using so many underscores? |
|
Wow! Amazing work! Here are my 2¢ for some of the renaming concerns. I'm writing out of order: My biggest concern is consistency. My second concern is ease of use - which balances ease of maintainability with fast and easy coding. Since I wrote the code over a number of years, my coding style shifted while writing different sections. This is something that hurts readability and I would love to fix. Internal Functions
Three underscores are used for internal functions. i.e., The three underscores are used to mark these internal functions. When less or more than three underscores are used, this is an inconsistency and it should be fixed. Re: Full Expansion?The way I understood it, the core logic behind choosing array was to avoid contention regarding the abbreviated names and conform to common practices (in C and other languages). I doubt str or ptr are contentious and both of them conform to common practices. However, I was reading through some of the changes and loved the readability. In many cases, such as POINTER and STRING macros, I think full expansion works beautifully! Thanks! Then again, when it comes to function names, I feel
|
|
Thanks. Lot of thought in your reply. Appreciate the discussion.
Don't worry. It wasn't a lot of time. I'm an avid grep and vim user. I realized showing full expansion in an entire files would help the discussion. It's a process to standardized everything. At this point it's easy to go back and change whatever we want. So my time is not wasted if we decide to do something different. Also, I stopped before going down a long rabbit hole like len/length noted above...
These are my two of my top concerns as well. I would also add readability and maintainability as others that vy for attention. It is EXTREMELY difficult to create a consistently coding style that is both readable and easy to remember and therefore use... I propose this axiom: Consistently easy to remember so we maintain readable meaning.
Consistent Abbreviation ProblemsIn truth there is no such thing as consistent abbreviation in code:
There are multiple problems here. The Ultimate FlexibilityIn theory, we could create a MACRO for each use case allowing a person to rename all exposed functions in a consistent manner. We're already quite a ways down that road already. We would need a MACRO for a_to_b function and we would also need a MACRO for each type that could be reused in these functions. Essentially we would end up with a glossary that is user defined. This is definitely the most flexible approach. But is it the best? I'm not sure... The downside to being this flexible is that it makes building on non-standard implementations problematic for the greater ecosystem. But since Facil is C code this is less problems and obviously there isn't really an ecosystem surrounding the framework at present. So I'm inclined to think that providing a flexible API may actually strengthen the library... However, documentation is another problem. We need to figure out how to provide re-written documentation for custom named APIs. I'm not sure of an easy way to do this. But I think we need to figure that out before we release the MACRO concept that you've been working on... International Non-English UsersYou make a good case for shortened wording because they are always easier to remember than long words for non-native speakers. I personally speak six languages at some level of proficiency so I can readily empathize with your point towards brevity. However, I also think that anchoring to a single language gives more definition than simply memorising characters. Most programming jobs originate from companies in English speaking countries, so English is the natural choice as an anchor language. abc2xyz vs abc_to_xyzThe abc2xyz syntax is ancient as the C language and pretty much everyone understands its usage. I like this syntax personally, but at the same time, I also like the differentiation between fiobj_string and cstr. I feel like a framework may need to be more verbose because it's data types are NOT standard C. This puts a goo argument for using to syntax even though it is extremely verbose. So the coder in me really wants the abc2xyz but the software architect's gut says that to will create less bugs precisely because it is verbose. What is most important?Differentiating data types is probably more important than fast data entry since IDEs can fill in the blanks for us. But I should note that I'm biased because I'm a fast typist myself. 22 characters doesn't seem too long for a function call. The Linux Kernel has much longer calls sometimes... By making the API use narrative English we create a self documenting code that tells the story of what the computer is doing. I like that aspect a LOT. Line BoundariesThis is why abbreviations were initially used. But in an era where even small laptops have 1080p displays the concern of wrapping code at 80 characters is probably not something we should care about anymore. (I know, some purists will shoot me now...) If we want to honor 80 character boundaries we need to abbreviate everything to 3 chars. Otherwise, we need to realize that screens are much bigger than 640x480 these days and lighten up on the whole thing. Standard SuffixesIf we are going to use abbreviated suffixes for _len I think we should also do the same for other common use cases. _dup, _cap, _ptr are obvious choices. I think using 3-4 letter abbreviations makes sense. (With the caveat that we should not abbreviate float - because nobody does.) ConclusionI think this really has to be an all or nothing choice. The reasons for abbreviating data types are the same reasons for abbreviating function names. We can however, have separate rules in MACROs vs code. I very much believe we should stick with verbose long macros because they DO force use to think about their meaning more closely. Using the Having rambled a bit exposing my thoughts I propose:
I really feel the more we can use the code as the documentation the better off this API will be... Let me know if the above conclusion makes sense. I'll update my branch based on these thoughts... |
TL;DR;
I agree with the However, where string MACROS are concerned, I totally agree that
I obviously agree with I'm not against this change, I just haven't seen
Yes. Definitely.
I think these are, except For example, Where API is concerned, I think channel and subscriptions are too context specific to be comfortably abbreviated unless the context is present (i.e.,
Could you give an example for this? I'm not sure I understand the idea. Also, what is the added benefit in adding an
I'll write about this a little later. In short, I believe the As an added optimization, it will also move all type conversions to a different placement in the auto-complete list. For example, writing
That would be great. I already tried my best to author Doxygen style comments (although I'm not fluent in the However, I truly dislike the Doxygen output. I find it very hard to locate the information I need using Doxygen documentation. I would much rather see the output re-formatted into Markdown and made available using the facil.io website. Reasoning and Discussion
True. I always think of readability and maintainability as integral parts of ease of use. I agree with this core outlook.
I think this will introduce a number of issues as the framework and the ecosystem evolves. This type of flexibility means that questions on SO will be harder to answer, tutorials harder to write, etc'. It also means different projects have different APIs, which can't be always comfortable.
Yes, this is an issue. I tried to solve this when authoring the core-library documentation. However, this precludes automation for the documentation. Yet another reason for the main API to avoid MACROs for function names.
I agree, English is the natural choice. However, making things a little easier for non-native speakers, by adopting well established abbreviations where appropriate, wouldn't hurt.
IMHO, it's more important to make the coder in you happy. Happy coders write better code. In other words, I believe that happiness trumps verbosity where maintenance, readability and coding are concerned. Also see my note above regarding auto-complete optimization.
IMHO, we should. As long as there are framework users that care about line length, we should care about line length as well. Besides: I don't want to get into lengthly arguments about having multiple files open side by side and all that. The technology makes line-lengths far less of an issue... but biology still means that moving the eyes sideways will tire the eye muscles than moving the eyes up and down. This means that short lines are always better for long working hours and our health.
I think 3-4 letters is a reasonable abbreviation length. However, I want to raise the question of Unlike their names, and much like the standard library's |
It's about grammaring consistency... str is not a word. String is. arr and ary are not words. Array is. We should be consistent in expansion.
This is also a suggestion based on name consistency... All other suffixes are three letters. Also, cap is the actual English abbreviation for capacity...
a variable named
Because cstr and other native types are used regularly and it's not easy to imply from explicit context without a lot of vertical scrolling in some cases. This will make code more readable...
Agreed. This is where the MACROs come in...
Does this currently work like that or is this something that you are suggesting to change...?
Doxydown is much better. Generates markdown like you would expect exactly for the use case you mentioned...
Agreed. While the MACRO thing is cool it needs to be limited in scope.
This is my fear in going down that road as well.
After reading this I agree. Line length is an issue then. 80 char?
I'll have to dig into those points more directly before addressing... Bottom Lines
I really need to go back and familiarize myself with the unmodified source again before I dig deeper into this. I've got too many concurrent version stuck in my head. I think the next step is to generate a list of functions and make sure they are to everyone's liking. After that, we can come back to variable naming etc. But that seems like a good baby step. As always. THanks for the input... |
|
I would like to thank you for this discussion. I feel that this is really helping me understand naming choices, where before I was either making my choices unaware, copying other people's choices, or making the wrong choices. Consistency
I think we understand consistency in a different way. For example: I have just discovered that the Array API uses Another example: both array and hash types use When I think of consistency, I think that:
What I'm not thinking that the results for the naming decisions should be consistently the same. I suspect that you're taking consistency to a meta-level, where we consistently make naming decisions based on the same naming logic / results. IMHO, we should consider each naming decision separately unless it had been considered before.
|
Abbreviation Consistency
I feel strongly that we should be consistent in naming either through abbreviating or expanding to full words or at least to keep lengths the same. It's a big pet peeve of many senior coders I know. To be clear, I'm fine with using array if we expand str to string. I'm find using str if we abbreviate array to the more standard arr. But both need the same rules of abbreviation and expansion. This may not annoy non-English speakers but it WILL drive English speaking programmers nuts if the abbreviations are not relatively consistent...
This is the consistency that I'm pushing for... (In fact, how the the discussion got started ;-) MACROs and a Single API
I was suggesting that the purpose of the FIOBJ_XXX_NAME seem to be used specifically to help people choose their own abbreviations. You've explained a little further on that Macros have a slightly different use case.
Thanks for the explanation. Makes sense. Auto-Complete Optimization
Which branch is this in? I've got too many versions of code in my head! hehehe... Doxydown vs DoxygenDoxydown a separate Perl script that is MUCH smaller than the Doxygen monstrocity. (Doxygen really is a monster!!) I've got a highly modified branch laying around that adds full Lua support and a few other languages. I'd like to rewrite the tool at some point in C with configuration via some external .rc file but I've not gotten that far yet... f_xyz_ prefix
No. I'm thinking specifically of cases like the HTTP1 code where a lot of 'fiobj_strings' are used and then some Let's table this one for now. I'll illustrate it for you once we have the abbreviation discussion finished... The Big Decision:I think we really need to finish the abbreviation discussion and come to a conclusion. There are a couple ways to go to keep code conversational and familiar.
I suggest that we choose one of these styles completely and conform everything to this consistency. There are pros and cons to both styles. Here's my thoughts:
We really need to decide which direction we go and then build out the rules for our naming style based on this. Personally, I've used both styles and in this project I can argue both sides of the issue very strongly. I provided an eloquent argument above for why I think expanding may be better here. But it really comes down to understanding the variety of use cases that OUR USERS present. Facil will probably be used most for high workload, heavy throughput, micro services. It may also be used as a backing library for custom scriptable web application servers. While Facil could be used for large applications, it is more likely that it will be in the underbelly of a scriptable framework that the large application uses. Personally, I hope to create a database-first framework for web application requiring zero custom API code. (All business logic in stored procs) For my usage either style works - so I really don't care which direction we go. But it does need some cleanup and consistency... |
|
Well has been an amazing read. If you two collaborated on a book I'd buy 20 for the shelf and hand them out. Sry / Sorry just chillin on the sidelines loving this. :)
… On Jun 4, 2019, at 11:54 AM, frink ***@***.***> wrote:
Abbreviation Consistency
What I'm not thinking that the results for the naming decisions should be consistently the same.
I feel strongly that we should be consistent in naming either through abbreviating or expanding to full words or at least to keep lengths the same. It's a big pet peeve of many senior coders I know. To be clear, I'm fine with using array if we expand str to string. I'm find using str if we abbreviate array to the more standard arr. But both need the same rules of abbreviation and expansion. This may not annoy non-English speakers but it WILL drive English speaking programmers nuts if the abbreviations are not relatively consistent...
After we decide on an abbreviation (which I believe to be needed) we should apply this consistently to all places where capacity appears (strings, arrays, hash maps, etc').
This is the consistency that I'm pushing for... (In fact, how the the discussion got started ;-)
MACROs and a Single API
Maybe I don't understand you. Are you suggesting that functions with long names (i.e., fiobj_string_capacity) will offer helper abbreviated MACROs (fiobj_str_capa)?
I was suggesting that the purpose of the FIOBJ_XXX_NAME seem to be used specifically to help people choose their own abbreviations. You've explained a little further on that Macros have a slightly different use case.
The core types in the fio-stl.h library are used within the core library in different ways.
Thanks for the explanation. Makes sense.
Auto-Complete Optimization
Yes, the new abc2xyz style (i.e., fiobj2cstr) was adopted because it added this auto-complete optimization which I found very useful.
Which branch is this in? I've got too many versions of code in my head! hehehe...
Doxydown vs Doxygen
Doxydown a separate Perl script that is MUCH smaller than the Doxygen monstrocity. (Doxygen really is a monster!!) I've got a highly modified branch laying around that adds full Lua support and a few other languages. I'd like to rewrite the tool at some point in C with configuration via some external .rc file but I've not gotten that far yet...
f_xyz_ prefix
Is this your example?
No. I'm thinking specifically of cases like the HTTP1 code where a lot of fiobj_strings are used and then some cstr and an fiobj_array. I found the code almost meaningless as I read through it and had to keep scrolling back to see what a variable type is...
Let's table this one for now. I'll illustrate it for you once we have the abbreviation discussion finished...
The Big Decision:
I think we really need to finish the abbreviation discussion and come to a conclusion. There are a couple ways to go to keep code conversational and familiar.
_shorthand - Use abbreviated types and actions (e.g. fiobj_str_dup / `fiobj_str2cstr)
This means functions will be short but may not be readable as common English
Core types more than 4 letters should be abbreviated to 3 letter abbreviations
Actions suffixes (_dup, _len, _capa) should be abbreviated to 3 or 4 letters
Conversions should use the 2 conjunction
_conversational - Use words for types and actions (e.g. fiobj_string_duplicate, fiobj_string_to_cstr)
This means function names will be longer but the code will be more conversationally readable
Core types should probably be named between 3 and 7 letters to avoid insane lengths
Action suffixes (_duplicate, _length, _capacity) should seek to stay below 9 characters
Conversions should use the to conjunction to keep things readable
I suggest that we choose one of these styles completely and conform everything to this consistency. There are pros and cons to both styles. Here's my thoughts:
shorthand coding style
standard C libraries and small C projects tend to use this style
helps solo coders quickly write small projects
focused on getting work done and may not invite junior coders to read deeper
often requires extensive comments to be considered code complete
easier for code to be misunderstood when scanned
better for those coding in text editors
generally requires more work for English speakers to memorize
APIs that use this style require more extensive documentation
conversational coding style
GUI toolkits and C++ tend to use variations of this style
helps wrangle massive projects with many junior coders
focused on explaining the code as completely self documenting with few comments
often requires excessive typing to write much code (autocomplete is your friend)
easier for code to be too long and wrap lines
better for those coding in IDEs
generally requires more work for non-English speakers to memorize
APIs that use this style are naturally self documenting
We really need to decide which direction we go and then build out the rules for our naming style based on this. Personally, I've used both styles and in this project I can argue both sides of the issue very strongly.
I provided an eloquent argument above for why I think expanding may be better here. But it really comes down to understanding the variety of use cases that OUR USERS present. Facil will probably be used most for high workload, heavy throughput, micro services. It may also be used as a backing library for custom scriptable web application servers. While Facil could be used for large applications, it is more likely that it will be in the underbelly of a scriptable framework that the large application uses.
Personally, I hope to create a database-first framework for web application requiring zero custom API code. (All business logic in stored procs) For my usage either style works - so I really don't care which direction we go. But it does need some cleanup and consistency...
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub <#60?email_source=notifications&email_token=AH5NB6MVDULJ3JMR6TWIESTPY2F3TA5CNFSM4HK374K2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODW5A3LQ#issuecomment-498732462>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH5NB6KN3UONS7QIWIUOH5DPY2F3TANCNFSM4HK374KQ>.
|
|
Thanks @pr0con. Most people don't realize how much code style plays into the utility of an API and they let their egos get in the way of everything. I once worked on a project where they had no coding style, most database tables were named one thing while the business unit used a different name. There was no verb consistency and it was over 250k sloc. Talk about a nightmare!!! That's when I started caring about naming conventions and consistency. What do you think? Are you an abbreviation or expanded word type person? |
|
@frink , I want to think more about this, but I'll write a short response to a few things I hope you consider:
This all-or-nothing approach isn't based on a logical argument. I don't see the harm in working with both approaches in order to get the best of both worlds according to context. For example,
Grab the #define FIO_FIOBJ 1
#define FIO_LOG 1
#include "fio-stl.h"
// ... |
|
I guess overtime my discardable variable names take on an abbreviated L&F and functions/constants/types get spelled out… I am a self taught programmer and am no where near the level you guys are so I am learning a-lot reading this. I’ve written API’s with other languages and just picked up C about 6 months ago. I usually start with a web-socket client server project just to get the feel of a language. Facil.io <http://facil.io/> seemed liked a jack-knife library and worked like a charm for the project. C still at times looks foreign to me but already by the discussion i see taking place I feel like you guys are on the path to creating a nice clean legible API. IMHO from a more novice point of view and looking at the discussion the spelled out system looks and feels cleaner to me. But the way the brain works(in my case) well knowns across languages such as str ary & len read fine to for type defs. Forget about the MACRO thing thats something new to me lol. Like I said this discussion has become a great source of knowledge listening to some true C developers converse.
… On Jun 4, 2019, at 12:24 PM, frink ***@***.***> wrote:
Thanks @pr0con <https://github.com/pr0con>.
Most people don't realize how much code style plays into the utility of an API and they let their egos get in the way of everything. I once worked on a project where they had no coding style, most database tables were named one thing while the business unit used a different name. There was no verb consistency and it was over 250k sloc. Talk about a nightmare!!!
That's when I started caring about naming conventions and consistency.
What do you think? Are you an abbreviation or expanded word type person?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub <#60?email_source=notifications&email_token=AH5NB6MSQOO3N32R6I3COJLPY2JMFA5CNFSM4HK374K2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODW5DVYI#issuecomment-498744033>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH5NB6ODE7YZEGPTRY4U66LPY2JMFANCNFSM4HK374KQ>.
|
|
@pr0con - I'd love to read your 2¢. |
|
by the way jack-knife in my world == “solid, tight, very well put together”. There Bo thats my two cents. ;).
… On Jun 4, 2019, at 1:02 PM, Bo ***@***.***> wrote:
@pr0con <https://github.com/pr0con> - I'd love to read your 2¢.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub <#60?email_source=notifications&email_token=AH5NB6K36MXSBNL7K4U4CRLPY2N2RA5CNFSM4HK374K2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODW5HDBQ#issuecomment-498758022>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AH5NB6IEEC5NKZUUB6T4Q2TPY2N2RANCNFSM4HK374KQ>.
|
|
@boazsegev Thanks.
Correct. My approach is not based on logic in the pedagogic sense but rather on linguistic grammar consistency and personal anecdote. I believe that we SHOULD use the same naming conventions and grammar in all cases within any library. But, adherence to the same internal standard need not be a strictly all-or-nothing approach. There are several points of contention which needed to be decided separately. These decisions inform the style guide and present definition of code code with relation to the library used. Here are a few points that need to be addressed separately.
So I'm confused. Do you want to expand string now? I thought you wanted to expand array but NOT string. AS AN ASIDE: I was talking to one of my mentors tonight who suggested that any seasoned coder should be a fast typist and therefore not concerned about the amount of time it takes to type something but rather the amount of time it takes to understand something a year later when reading it again. His impression, after coding for 40+ years, is that it is always better to have long names because it makes maintenance easier. Since he trained me, I'm really not surprised to learn we have the same opinion.... I'm standing by... Let me know what you conclude! |
|
@pr0con Thanks.
However, if |
|
Hi @fink , Thank you for your time and for your considerably knowledgeable input. I'm fairly convinced that verbosity is more beneficial most of the time. However, too much verbosity is makes code harder to read, harder to author and harder to debug using common debugging tools. For this reason, I won't subscribe to the all-or-nothing approach. My decision is to go with a mostly verbose API, where:
If you think I missed anything in my considerations, please let me know. ReasoningSome abbreviations help readabilityIMHO, when well established abbreviations are used (i.e., In fact, I think developers expect these abbreviations and breaking this expectation distracts them. This is especially true where common practices are concerned. Consider the following example, and notice how the verbosity actually requires more attention: // verbose
for(int temporary_counter = 0; temporary_counter < 10;
temporary_counter = temporary_counter + 1) {
}
// common shorthand
for(int i = 0; i < 10; ++i) {
}The API is also used by the other developer tools (IDE etc')The API we choose is used mostly for reading, but also for coding, debugging and optimizing. When debugging, optimizing or coding, variable and function names are used by these tools that often have limited space for function / variable names. In addition, the auto-complete feature in many IDEs is often used as a good-enough replacement for API documentation when general (but not specific) knowledge of the API exists. For this reason, function prefixes have an additional function. Spacing characters have a strong functionality. Using For example, ImplicationsI believe the following abbreviations don't affect readability even when out of context: The following abbreviations may appear in context: These lists aren't complete, but I believe they provide a good enough explanation.
|
|
@boazsegev - Thanks for clarifications. If I understand correctly, the goal is to abbreviate without obfuscation. I'm concerned about going a file at a time with renaming. It is much safer to globally replace word at a time so that all references stay intact. In the above proposal there are not many that need to change so I should be able to get the code to conform to that spec quickly. Anything that affects deprecated APIs will still be changed because I am doing global search and replace. I'll branch off of 0.8.x for this. Because of the nature of renaming it is better in this case only to do a monolithic commit since git considers any change to a line a complete line change. But most of the style described above has already been implemented and just needs some tidying up. Give me until the end of the week and I should have the abbreviations translated consistently. If you do any coding work on the 0.8.x between now and then I will review and merge your changes into my branch so that it doesn't stop development. Then I can go back through file by file and do small PRs fine tuning internal variables per function. Sounds like we got a plan. Thanks!
I am a self-taught developer and have preferred to hired mostly self-taught developers over my 20+ year career. Yet I never encountered So my conclusion is that |
That's one way to put it :) On the other hand, readability is the higher concern, so missing possible abbreviations isn't a big deal. I'm just thinking pragmatically and I believe some abbreviations have become a written dev language rather then an abbreviation. I think about it as expanding the dictionary so deeply ingrained "abbreviations" (such as
That's a good point. The counter argument is that by updating the files "manually" ( This would also help us build a porting guide / script with a list of changes. Also, finalizing the
Actually, I started with C++ (where I would name these as For me I like
Yes, please do. I've made a few changes, changing small letter MACROs (uncapitalized) into inline functions and improving consistency for the In addition, one of my latest commits updates the Perhaps we could start with finalizing I'll hold off from committing any further updates. |
|
Hi @frink , FYI: the FIOBJ data types were re-written from the ground up. Currently, the 0.8.0 branch bypasses the new FIOBJ types, but the old implementation should be totally replaced with the implementation in the This would make it a little hard to perform an "inplace" Anyway, I'll postpone any further changes for a little while. I need to write a quartet anyway, so I'll focus on my music. Kindly, |
Hehe. You're funny. Obviously not a native English speaker... ;-P
I don't quite understand your vision there yet. But I expect that I just need to spend a little bit more time in the code. Now that we have a direction, that's where I'm headed... |
My Vision for 0.8.0
I believe C is a beautiful language and many more developers would enjoy it if a few more basic tools were made available to help beginners. And I know facil.io has these tools and could be used to make developers happy, not just when writing network applications, but when coding any application. My vision for 0.8.0 is to separate the IO core library ( It came about because I kept copying pieces from facil.io for non-network projects. I think one of the pieces I kept reusing most was the CLI (command line interface) API, but the simple types (lists, arrays, hash maps and strings) and the memory allocator were also high on the list. This made me think "I should really separate the non-IO library from the IO library", which would also make it easier for other developers to enjoy facil.io. Why the FIOBJ changes?I though about it as a small STL, much like C++ has, only for C, and drew the line at JSON support (since every language today could need that). JSON support meant that the dynamic types (FIOBJ) had to move back into the core library. This was a wonderful opportunity to minimize code duplication that occurred between the FIOBJ types and the core (MACRO based) types and implement much of what I've learned when I extracted the FIOBJ dependency from the core library in version 0.7.0. It was a good time to improve the pointer tagging system as well, improving type identification speeds significantly and minimizing some memory allocations. However, some FIOBJ types / extensions are more network oriented, such as the I decided these extensions should be kept out of the core library, even if it means I will have to port or re-write some of their code to manage the new way FIOBJ objects can be extended (the new pointer tagging and virtual function structure). The reason was simple - these extensions weren't required to support JSON. So I rewrote the FIOBJ type system using only the Macro based types (Arrays, Hash Maps, Strings), added the special code required to support numbers in a way that minimizes memory allocations. This took 1,437 lines (including comments) and now we have a FIOBJ type-system that's about 20% faster (good) and sometimes recursive (which is less abuse resistant). Now core FIOBJ types (without the extensions) and JSON parsing / formatting can be used in non-network programs with ease, copying a single file ( That's why the FIOBJ changes. |
Thanks. Makes sense.
I've never heard anyone suggest recursion invited abuse. What abuse are you referencing?
Most implementations of Mustache (including two I've written in Lua and PHP) just use a JSON type representation natively with the addition of juggling context and partials separately. Is that how the |
Incorrect use will result in stack explosion. i.e., freeing a deeply nested data structure will recursively free each object, including array / hash objects. This might result in a stack explosion. Since JSON and HTTP form data are the only unsafe input source (currently), they should be protected against malicious data that will absue the nesting level. The HTTP form parser is limited to floating 32 levels of nesting (32 levels starting at entry point, which might shift according to application usage). The JSON implementation protects against this by limiting nesting input and output. The current limits should be updated since they aren't consistent. The output nesting level is limited to These are low limits, but they are still higher than test number 18 in the JSON testing suite (which expects a JSON parser failure after 21 nested levels).
The When
The Since JSON can be easily parsed into FIOBJ objects, this approach offers more flexibility than requiring a JSON input. |
|
I get it now. How bad does Facil blow up if nesting is too deep? |
|
BTW, how's the progress on the renaming?
Depends. There are generally two approaches:
The general rule is that external input processing should result in quiet failures, as to prevent malicious attacks, while internal causes (programming errors) should crash as early as possible. Specifically:
|
I"m behind. I've got a holiday coming up that will render me offline until Tuesday. Got about an hour and a half left on the whole thing. So Tuesday night US time Wednesday morning Russian time is when I'll likely report things finished.
Definitely for freeing reciprocal reference nesting. You may need to use some sort of reference counting to make sure you don't continue in recursion. In theory, you could do a two step process. One that would unset the linkage between the parent and child while storing a link in a new array temporarily. Then looping through the newly created array and freeing everything. (This I've seen reciprocal references how it is usually handled in higher level languages. Should work in C too.) |
Happy holiday. Have fun. I guess I'll be waiting, since I've got many small updates to do in the
One of the changes I want to perform in the I don't think I'll add other guards until I actually find a practical use-case for recursive nesting that isn't an error. |
|
@fink , thank you for your help and input. Since no PR arrived, I'm assuming you got bogged down with actual work (the one that puts food on the table)...? If so, I'll take over from here. If you have anything you want to add, let me know. Thanks again! |
I realize this may seem like grasping at straws but spending tons of time programing these things become quite an annoyance. Both Google and Github searches show clearly that ARR instead of ARY is the preferred abbreviation for array. While this would not be a big concern in a vacuum, in combining several libraries remembering that Facil says ARY while all other libs say ARR is frustrating. For these reasons I'm suggesting that for the next major version we should standardize this abbreviation for everyone and grep all ARY/ary replacing with ARR/arr. I am willing to take on this task if we decide to do it...
The biggest concern is that this will impact backwards compatibility. So it needs to be planned instead of just sending a pull request in a vacuum.
The text was updated successfully, but these errors were encountered: