Adds block about Angular's low-level functions #768

sergiocruz · 2016-09-04T15:34:17Z

Angular 1.x low-level functions should be avoided in favor of language features that are available natively in its newest versions (ES2015+). For most other cases a utility library like lodash will do wonders as well.

Although it was not mentioned in the guide, avoiding low-level also helps when upgrading to Angular 2. With the help of TypeScript and newest language features, Angular 2 is able to shift more responsibility to the language itself. Therefore functions like angular.copy(), angular.isUndefined() and angular.equals() is simply not found within Angular 2.

joshstar · 2016-09-04T22:51:12Z

I feel it would be better if this was prefaced "If you plan on migrating to Angular 2 or using ES2015+". There are a lot of angularjs apps that follow this guide that have but have no plans on moving up to Angular 2, and browser support limits a lot of them from using ES2015 unless a polyfill or something like Typescript is used.

gkalpak · 2016-09-04T23:27:57Z

a1/README.md

+
+  *Why?*: You can replace a lot Angular's low-level functions with native ES2015+ functionality such as [`Object.assign()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) for copying objects and the [Spread Syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Copy_an_array) for copying arrays _(ie. `[...arr1]`)_.
+
+  - Note: Use a utility library like [lodash](https://lodash.com/docs/4.15.0) if you need additional functionality that is not available natively in the newest versions of JavaScript.


It is better to omit 4.15.0 from the link (to always point to the latest version).

johnpapa · 2016-09-04T23:35:41Z

Please add a style code for this too. See other examples. I think where you put this is fine, i dont see a section that fits it, but i do like this new topic.

Perhaps style Y500

I'll read through it when I get a chance ... til then, love to get other people's feedback too.

BTW - we still need a style for components :)

Update README.md Update README.md Addressed comments made in johnpapa#768

sergiocruz · 2016-09-05T04:12:09Z

I addressed some of the comments made here, and pushed a new (squashed) commit adding:

intro paragraph
code samples
style number
some other revisions

Let me know what you all think :)

johnpapa · 2016-09-05T04:15:53Z

a1/README.md

+
+Angular 1.x ships with some [helper functions](https://docs.angularjs.org/api/ng/function) that are found within JavaScript natively. In such cases we should favor usage of native JavaScript functions instead of Angular's helper functions. In other cases where functionality is not found in JavaScript natively, we should turn to utility libraries such as [lodash](https://lodash.com/docs) to fill-in the gaps. Here are some examples:
+
+|Replace | With | |


Great examples ... net step is to put these examples as code examples, and in the format of the avoid/recommend that the guide uses.

No problem! I decided to use a table here as it was a lots os micro-examples, but will move to that style then (will probably trim down the examples though).

johnpapa · 2016-09-05T04:18:23Z

coming along well!

Update README.md Update README.md Addressed comments made in johnpapa#768 Low level functions: added code samples and more why's

sergiocruz · 2016-09-05T04:59:13Z

I added another commit adding the code samples and the two additional why's.

gkalpak · 2016-09-05T06:38:39Z

a1/README.md

@@ -3268,6 +3269,95 @@ Use [Gulp](http://gulpjs.com) or [Grunt](http://gruntjs.com) for creating automa

 **[Back to top](#table-of-contents)**

+## Low Level Functions
+
+Angular 1.x ships with some [helper functions](https://docs.angularjs.org/api/ng/function) that are found within JavaScript natively. In such cases we should favor usage of native JavaScript functions instead of Angular's helper functions. In other cases where functionality is not found in JavaScript natively, we should turn to utility libraries such as [lodash](https://lodash.com/docs) to fill-in the gaps.


I think it should be (somehow) clarified that not all. functions listed in the linked docs section are to be avoided. E.g. module, injector, bootstrap, element are fine to use.

That's a very good point. I wonder how to balance that with the fact that if one ever wants to upgrade to Angular 2, he or she will have to get rid of these method calls anyway.

Just mentioning this since eventual upgrade to Angular 2 is one of the why's.

Update README.md Update README.md Addressed comments made in johnpapa#768 Low level functions: added code samples and more why's Angular Helper Functions: more reviews in johnpapa#768

sergiocruz · 2016-09-05T14:55:59Z

All righty, added another commit addressing some more of the comments including:

Renamed "Low-level Functions" to "Helper Functions" (I believe the meaning is clearer now)
Added a couple of helper fn examples in the intro paragraph so users know what type of functions we are referring to when we mention helper functions
Added a note advising users to understand the differences in implementation

Again, let me know what you all think :)

gkalpak · 2016-09-05T16:55:57Z

a1/README.md

+
+  - Avoid using Angular helper functions such as `angular.copy()`, `angular.extend()` or even `angular.isUndefined()`.
+
+  *Why?*: You can replace a lot Angular's helper functions with native ES2015+ functionality such as [`Object.assign()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) for copying objects and the [Spread Syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Copy_an_array) for copying arrays _(ie. `[...arr1]`)_.


a lot _of_ Angular's

gkalpak · 2016-09-05T17:07:41Z

Another reason you might want to mention is:

These helpers are exposed publicly for convenience, but they are primarily intended for Angular's internal use. What this means is that, while they are optimized for Angular's needs, they may not handle all edge-cases (or handle specific - not interesting to Angular - cases sub-optimally).

Update README.md Update README.md Addressed comments made in johnpapa#768 Low level functions: added code samples and more why's Angular Helper Functions: more reviews in johnpapa#768 Angular Helper Functions: addressing more comments on johnpapa#768

sergiocruz · 2016-09-05T17:29:53Z

Thank you, I just pushed another commit.

sergiocruz · 2016-09-08T13:48:11Z

Hey @johnpapa are there any reviews left to add before we are able to merge this in?

johnpapa · 2016-09-14T02:05:55Z

I want to get Pete Bacon Darwin's eyes on this too

gkalpak · 2016-09-14T11:46:24Z

/summon @petebacondarwin

petebacondarwin · 2016-09-14T12:35:01Z

While I would be delighted if we had never exposed our "helper" functions to application developers in the first place, because it would make our maintenance of the project easier, I am still not clear how it benefits application developers not to use them.

Sure, if you are going to upgrade to Angular 2 then you would need to change to alternative helpers. But compared the the significant changes that will need to be made across the board for an app migration, such as completely reworking any directives that directly manipulate the DOM, I think that the cost of swapping out things like angular.isArray with Array.isArray is pretty trivial.

Also, I am not entirely convinced that there is much of a performance saving in many cases either. Often the helper function delegates to the native method if it is available anyway.

Moreover, as is pointed out by @gkalpak, the helpers often work differently to their native counterparts, which often leads to simpler application code. E.g.

angular.forEach(obj, function(value) {
  console.log(value);
});

compared to

Object.keys(obj).forEach(function(key) {
  console.log(obj[key]);
});

The only reason that I feel holds water is that using standard native JavaScript functions rather than Angular helpers allows more idiomatic JavaScript code that is easier for a non-Angular developers to follow.

So I guess my opinion is that I am not against people using native methods if they like, but I don't feel strongly that people should always avoid using them. So I have no problem with this being added to the style guide but personally I would make it a very soft suggestion rather than a strong recommendation.

johnpapa · 2016-09-14T16:08:11Z

I agree with you Pete ... especially in this

The only reason that I feel holds water is that using standard native JavaScript functions rather than Angular helpers allows more idiomatic JavaScript code that is easier for a non-Angular developers to follow.

And also with this ...

... I would make it a very soft suggestion rather than a strong recommendation.

Update README.md Update README.md Addressed comments made in johnpapa#768 Low level functions: added code samples and more why's Angular Helper Functions: more reviews in johnpapa#768 Angular Helper Functions: addressing more comments on johnpapa#768 Helper functions: Changed language to sound more like a soft suggestion

Getting the latest

sergiocruz · 2016-09-21T00:49:54Z

@johnpapa I pushed a new commit changing the language a bit to make it sound more like a soft suggestion with examples. Hopefully this is better, but still open to additional suggestions :)

petebacondarwin · 2016-09-21T06:06:41Z

Reads better for me.

sergiocruz changed the title ~~Add block about Angular's low-level functions~~ Adds block about Angular's low-level functions Sep 4, 2016

gkalpak reviewed Sep 4, 2016
View reviewed changes

sergiocruz force-pushed the master branch from 29cb651 to 20df6a2 Compare September 5, 2016 04:10

sergiocruz added a commit to sergiocruz/angular-styleguide that referenced this pull request Sep 5, 2016

adds block about angular low-level functions

20df6a2

Update README.md Update README.md Addressed comments made in johnpapa#768

johnpapa reviewed Sep 5, 2016
View reviewed changes

sergiocruz force-pushed the master branch from 20df6a2 to df1453c Compare September 5, 2016 04:57

sergiocruz added a commit to sergiocruz/angular-styleguide that referenced this pull request Sep 5, 2016

adds block about angular low-level functions

df1453c

Update README.md Update README.md Addressed comments made in johnpapa#768 Low level functions: added code samples and more why's

gkalpak reviewed Sep 5, 2016
View reviewed changes

sergiocruz force-pushed the master branch from df1453c to c93732e Compare September 5, 2016 14:49

gkalpak reviewed Sep 5, 2016
View reviewed changes

sergiocruz force-pushed the master branch from c93732e to add37b9 Compare September 5, 2016 17:28

anteriovieira and others added 4 commits September 20, 2016 20:33

Original text and redundant removed

7c82e4d

fix typo: declaration => declarations

1ca751a

Fixed typo

2cc4278

sergiocruz force-pushed the master branch 2 times, most recently from 796d259 to d2c6568 Compare September 21, 2016 00:42

Merge pull request #3 from johnpapa/master

0562c20

Getting the latest

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adds block about Angular's low-level functions #768

Adds block about Angular's low-level functions #768

sergiocruz commented Sep 4, 2016

joshstar commented Sep 4, 2016

gkalpak Sep 4, 2016

johnpapa commented Sep 4, 2016

sergiocruz commented Sep 5, 2016 •

edited

johnpapa Sep 5, 2016

sergiocruz Sep 5, 2016

johnpapa commented Sep 5, 2016

sergiocruz commented Sep 5, 2016

gkalpak Sep 5, 2016

sergiocruz Sep 5, 2016

sergiocruz commented Sep 5, 2016

gkalpak Sep 5, 2016 •

edited

gkalpak commented Sep 5, 2016

sergiocruz commented Sep 5, 2016

sergiocruz commented Sep 8, 2016

johnpapa commented Sep 14, 2016

gkalpak commented Sep 14, 2016

petebacondarwin commented Sep 14, 2016 •

edited

johnpapa commented Sep 14, 2016 •

edited

sergiocruz commented Sep 21, 2016

petebacondarwin commented Sep 21, 2016


		Why?: You can replace a lot Angular's low-level functions with native ES2015+ functionality such as [`Object.assign()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) for copying objects and the [Spread Syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Copy_an_array) for copying arrays _(ie. `[...arr1]`)_.

		- Note: Use a utility library like [lodash](https://lodash.com/docs/4.15.0) if you need additional functionality that is not available natively in the newest versions of JavaScript.


		Angular 1.x ships with some [helper functions](https://docs.angularjs.org/api/ng/function) that are found within JavaScript natively. In such cases we should favor usage of native JavaScript functions instead of Angular's helper functions. In other cases where functionality is not found in JavaScript natively, we should turn to utility libraries such as [lodash](https://lodash.com/docs) to fill-in the gaps. Here are some examples:

		\|Replace \| With \| \|


		- Avoid using Angular helper functions such as `angular.copy()`, `angular.extend()` or even `angular.isUndefined()`.

		Why?: You can replace a lot Angular's helper functions with native ES2015+ functionality such as [`Object.assign()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) for copying objects and the [Spread Syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_operator#Copy_an_array) for copying arrays _(ie. `[...arr1]`)_.

Adds block about Angular's low-level functions #768

Are you sure you want to change the base?

Adds block about Angular's low-level functions #768

Conversation

sergiocruz commented Sep 4, 2016

joshstar commented Sep 4, 2016

gkalpak Sep 4, 2016

Choose a reason for hiding this comment

johnpapa commented Sep 4, 2016

sergiocruz commented Sep 5, 2016 • edited

johnpapa Sep 5, 2016

Choose a reason for hiding this comment

sergiocruz Sep 5, 2016

Choose a reason for hiding this comment

johnpapa commented Sep 5, 2016

sergiocruz commented Sep 5, 2016

gkalpak Sep 5, 2016

Choose a reason for hiding this comment

sergiocruz Sep 5, 2016

Choose a reason for hiding this comment

sergiocruz commented Sep 5, 2016

gkalpak Sep 5, 2016 • edited

Choose a reason for hiding this comment

gkalpak commented Sep 5, 2016

sergiocruz commented Sep 5, 2016

sergiocruz commented Sep 8, 2016

johnpapa commented Sep 14, 2016

gkalpak commented Sep 14, 2016

petebacondarwin commented Sep 14, 2016 • edited

johnpapa commented Sep 14, 2016 • edited

sergiocruz commented Sep 21, 2016

petebacondarwin commented Sep 21, 2016

sergiocruz commented Sep 5, 2016 •

edited

gkalpak Sep 5, 2016 •

edited

petebacondarwin commented Sep 14, 2016 •

edited

johnpapa commented Sep 14, 2016 •

edited