כשהתיעוד משקר

לא מזמן חבר הראה לי את הטריק הבא מסטאק אוברפלו כדי לייצר Directive ב Vue שמדמה את v-if ועושה אותו קצת יותר מתוחכם: https://stackoverflow.com/questions/43003976/a-custom-directive-similar-to-v-if-in-vuejs

זה הקוד המעניין מתוך השאלה שם:

Vue.directive('permission', (el, binding, vnode) => {
  if (!isUserGranted(binding.value)) {
    // replace HTMLElement with comment node
    const comment = document.createComment(' ');
    Object.defineProperty(comment, 'setAttribute', {
      value: () => undefined,
    });
    vnode.elm = comment;
    vnode.text = ' ';
    vnode.isComment = true;
    vnode.context = undefined;
    vnode.tag = undefined;
    vnode.data.directives = undefined;

    if (vnode.componentInstance) {
      vnode.componentInstance.$el = comment;
    }

    if (el.parentNode) {
      el.parentNode.replaceChild(comment, el);
    }
  }
});

הייתי צריך לקרוא את זה כמה פעמים בשביל להאמין, לא ידעתי שזה אפשרי. לא ידעתי שמותר לשנות את ה vnode מתוך Directive. נו אז הלכתי לתיעוד של Vue לראות מי צודק ומצאתי את המשפט שזכרתי ממנו:

Apart from el, you should treat these arguments as read-only and never modify them. If you need to share information across hooks, it is recommended to do so through element’s dataset.

עכשיו - מי צודק? התיעוד או Stack Overflow? ואם מישהו נתקל בתשובה בסטאק אוברפלו בלי שהכיר קודם את התיעוד?

אז האמת שזאת דוגמה נחמדה וממש לא היחידה בה תיעוד של ספריה מספר משהו אחד ובפועל אפשר לעשות דברים אחרים ואפילו את ההיפך. זה לא אומר שהתיעוד טועה או מרמה אתכם. התיעוד מסביר איך כותבי הספריה התכוונו שנשתמש בפיצ'ר מסוים, ודרך הבנת הכוונות שלהם איך כדאי לנו לכתוב קוד כדי שהוא יעבוד בביצועים טובים וימשיך לעבוד גם בגירסאות טובות של הספריה. בעולם הקוד הפתוח המשפט הנכון הוא לא "שברת, שילמת" אלא "שברת - אתה זוכה לשמור את החלקים", כלומר אם תבחר שלא להקשיב לתיעוד יכול להיות שהקוד שלך יעבוד אבל גם יכול להיות שהוא יפסיק לעבוד מתישהו (או רק במקרים מסוימים) בלי הודעה מוקדמת ובלי שיהיה לך את מי לשאול.

במקרה של הקוד שלנו החבר רצה להפעיל טריק דומה על Vue 3, אבל כצפוי העתקה פשוטה של הקוד לא ממש עבדה ובסופו של דבר נדרש קצת Refactoring כדי לפתור את הבעיה באמצעים אחרים. אגב אם יש מומחי Vue בין הקוראים שיודעים איך לתרגם את הקטע הזה ל Vue3 אני יודע לפחות על חבר אחד שמאוד ישמח לשמוע. תרגישו חופשי להציע רעיונות בתגובות.